<html>
<head>
<LINK REL="stylesheet" HREF="styles.css" TYPE="text/css">
<title>FOX-Toolkit</title>
<!-- HTML Copyright 2001 Paul Laufer -->
</head>
<body bgcolor=#ffffff link=#990033 vlink=#4a73ad alink=#ed004f text=#000000>
<!--header-->
<table align=center border=0 cellpadding=0 cellspacing=0 width=100% >
<tr><td bgcolor=silver colspan=5 align=right height=50><img src=art/oul_grey.gif align=left valign=top width=8 height=8><img src=art/foxlogo.png valign=bottom alt="FOX Toolkit" height=50 width=500 border=0 ></td>
<td bgcolor=#557faa valign=top align=right><img src=art/our.gif width=8 height=8></td>
</tr>
<!-- end header -->
<tr>
<td bgcolor=#557faa colspan=2 valign=top align=left> </td>
<td bgcolor=#557faa colspan=3><font color=#ffffff size=+1><center>
<!-- Page Title -->
Documentation: The FOX Registry
<!-- End Page Title -->
</center></font></td>
<td bgcolor=#557faa valign=top align=right> </td>
</tr>
<tr>
<td bgcolor=#557faa colspan=2> </td>
<td bgcolor=#ffffff valign=top align=left><img src=art/iul.gif width=8 height=8></td>
<td bgcolor=#ffffff> </td>
<td bgcolor=#ffffff valign=top align=right><img src=art/iur.gif width=8 height=8></td>
<td bgcolor=#557faa width=15> </td>
</tr>
<tr>
<td width=8 bgcolor=#557faa> </td>
<td valign=top bgcolor=#557faa link=#ffffff width=150>
<!-- start navbar content -->
<a href=fox.html><font color=#ffffff>Home</font></a><br>
<a href=news.html><font color=#ffffff>News</font></a><br>
<a href=download.html><font color=#ffffff>Download</font></a><br>
<a href=goals.html><font color=#ffffff>Goals & Approach</font></a><br>
<a href=doc.html><font color=#ffffff>Documentation</font></a><br>
<a href=faq.html><font color=#ffffff>FAQ</font></a><br>
<a href=rex.html><font color=#ffffff>FXRex</font></a><br>
<a href=screenshots.html><font color=#ffffff>Screenshots</font></a><br>
<br>
<a href=adie.html><font color=#ffffff>Adie</font></a><br>
<a href=pathfinder.html><font color=#ffffff>PathFinder</font></a><br>
<a href=calc.html><font color=#ffffff>FOX Calculator</font></a><br>
<br>
<a href=projects.html><font color=#ffffff>Projects</font></a><br>
<br>
<a href='http://fxpy.sourceforge.net'><font color=#ffffff>FXPy</font></a><br>
<a href='http://fxruby.sourceforge.net'><font color=#ffffff>FXRuby</font></a><br>
<a href='http://eiffelfox.sourceforge.net'><font color=#ffffff>EiffelFox</font></a><br>
<a href='http://eevolved.com/foxhole/'><font color=#ffffff>The FOX Hole</font></a><br>
<a href='http://takahr.dhis.portside.net/cgi-bin/rwiki.cgi?cmd=view;name=FOX+FAQ'><font color=#ffffff>Japanese Docs</font></a><br>
<br>
<center>
<a href="http://www.eff.org/br"><img SRC="art/freespeach.gif" border=0></a>
<p>
<a href="http://www.slashdot.org"><img SRC="art/slingerzbutton1.gif" border=0></a>
</center>
<!-- end navbar content -->
</td>
<td bgcolor=#ffffff> </td>
<td valign=top>
<!-- start main window content -->
<center><img src='art/foxstart.png'>
<BR><B>Documentation: The FOX Registry</B>
</center>
<p>
<p>
<b>What is a Registry?</b>
<hr>
Many applications have a need to read settings and configuration parameters
from configuration files. For example, it is common for applications
to remember which documents have been used recently with an application,
or what color a user has changed his/her window background to.
<P>Historically, each application has implemented its configuration files
in its own way, resulting in a plethora of file formats, each with their
own syntax and semantics. Moreover, many applications can only read,
and not write these configuration files; they rely on the user to fire
up an editor and edit them by hand.
<P>The FOX Registry class provides a simple method to keep track of configuration
parameters for FOX-based applications. Entries can be both read as
well as written, and settings will persist across invocations because the
system will write changed settings back to disk.
<P>Because the format is the same for all FOX applications, users will
have to learn only one [very simple] syntax in case they want to edit these
files by hand (although in most cases, registry files will probably be
manipulated by FOX programs only).
<p>
<p>
<b>Design Features of the FOX Registry</b>
<hr>
A registry mechanism should allow applications from many vendors or
organizations to coexist peacefully. Also, certain settings or configuration
parameters should be applied system wide, others ``suite-wide'' i.e.
for all applications produced by some organization. Yet other settings
apply only to one application.
<P>Tallying it all up, I've come up with the following list of requirements
for a registry system:
<BR>
<UL>
<LI>
<B>System-wide Desktop settings.</B> Configuration parameters which
apply to all users on a certain system, and apply to all applications.
For example, parameters specific to a certain FOX installation, such as
the location of icon files, images, and other such parameters.</LI>
<LI>
<B>System-wide Vendor settings</B>. These settings are determined
during installation of some vendor's application suite. They apply
to all applications which belong to the suite, and to all users on the
system.</LI>
<LI>
<B>System-wide Application settings.</B> These parameters apply to
a specific application, and to all users on the system.</LI>
<LI>
<B>Per-user Desktop settings. </B> Personal preferences that a specific
user has changed from the system-wide settings, and which apply to all
applications run by this user.</LI>
<LI>
<B>Per-user Vendor settings. </B>Similarly, a user of some application-suite
from a certain vendor may have changed a few things to suit his/her personal
preferences.</LI>
<LI>
<B>Per-user Application</B> settings. These are specific configurations
that a user may have changed while running an application.</LI>
</UL>
<P><BR>All settings can be ``shadowed'' or overridden. The general
rule is that more specific settings override more general ones. FOX
implements this by first loading system-wide settings, then per-user settings;
within each category, Desktop settings are shadowed by Vendor settings,
and those are overruled by Application settings.
<P>Registry settings are not shadowed when they've been changed, i.e. a
setting which was changed by an application is not replaced by a settings
entry loaded later.
<P>Finally, when settings are being written back to disk, they will automatically
become per-application, per-user settings. For instance, suppose
the default system-wide background color is ``gray.'' If the user
changes this, it will become a per-user default background color.
In other words, the system-wide settings are <I>never written</I>, except
perhaps when the application is being installed.
<P>The FOX settings database is comprised tyically of a number of files
which are placed in a certain directory structure. The organization
is as follows:
<BR>
<BR>
<CENTER><TABLE BORDER CELLSPACING=0 CELLPADDING=0 WIDTH="90%" BGCOLOR="#FFF8E1" NOSAVE >
<TR NOSAVE>
<TD NOSAVE><DIR>/Desktop</TD>
<TD NOSAVE>The settings database for all FOX applications. This contains
things such as double-click speed, default application fonts, and so on.</TD>
</TR>
<TR NOSAVE>
<TD NOSAVE><DIR>/<VENDOR>/<VENDOR></TD>
<TD NOSAVE>This contains all settings for all applications produced by
organization <VENDOR>. </TD>
</TR>
<TR NOSAVE>
<TD NOSAVE><DIR>/<VENDOR>/<APP></TD>
<TD>This contains all settings for application <APP> produced by organization
<VENDOR>.</TD>
</TR>
</TABLE></CENTER>
<P>The same directory structure applies for both system-wide settings and
per-user settings. The system-wide settings are found in directories:
<BLOCKQUOTE>/etc/foxrc
<BR>/usr/lib/FOX/foxrc
<BR>/usr/local/lib/FOX/foxrc</BLOCKQUOTE>
Per-user settings are found in:
<BLOCKQUOTE>$HOME/.foxrc</BLOCKQUOTE>
Which is a hidden directory directly under the users regular HOME directory.
<p>
<p>
<b>Format of a Registry File</b>
<hr>
The format for a FOX registry file is very similar to that of the SAMBA
configuration files. It consists of a number of sections, and each
section contains a number of registry entries. Each entry is a key/value
pair, where the key is the name of the particular entry, and the value
is a human-readable string representing the value of that key.
<P>For example:
<BR>
<BLOCKQUOTE><FONT FACE="Courier New,Courier"># A section</FONT>
<BR><FONT FACE="Courier New,Courier">[SETTINGS]</FONT>
<P><FONT FACE="Courier New,Courier"># An entry</FONT>
<BR><FONT FACE="Courier New,Courier">clickspeed = 400</FONT>
<BR><FONT FACE="Courier New,Courier">scrollspeed = 400</FONT>
<P><FONT FACE="Courier New,Courier"># Strings may have to be quoted if
they contain special characters</FONT>
<BR><FONT FACE="Courier New,Courier">tiger = "Tyger tyger burning bright\nIn
the forest of the night"</FONT>
<P><FONT FACE="Courier New,Courier">! Comment may also start with a bang</FONT>
<BR><FONT FACE="Courier New,Courier">tippause = 500</FONT>
<BR><FONT FACE="Courier New,Courier">tiptime = 300</FONT>
<BR> </BLOCKQUOTE>
<P><BR>The section names should consist of alphanumeric characters [A-Z,a-z,0-9],
and may contain underscores ``_'' also. Key names should consist
of alphanumeric characters [A-Z,a-z,0-9], underscores, dash ``-'' or periods
``.''. Value strings may consist of any non-blank character, except
``#'' or ``!'' which are used for comments. To incorporate these
and other non-printable characters, you may quote the string as shown above.
Special characters can be embedded into a quotable string using the regular
C-style backslash mechanism, i.e. ``\n'' is replaced by a newline; control
characters can be embedded using hex-notation: for instance, ``\FF'' represents
the byte 0xff.
<P>Under the MS-Windows Implementation of FOX, you can use either the ASCII,
human-readable implementation, or the binary version which uses the built-in
System Registry.
<p>
<p>
<b>Using the Registry</b>
<hr>
The FOX FXApp object contains an embedded FXRegistry object, which is
automatically read in when you start up using FXApp::init(). Likewise,
this registry is also automatically written back out when you terminate
the application using FXApp::exit().
<P>The <B><I>application name</I></B> and <B><I>vendor name</I></B> parameters
passed in when you construct the FXApp object are directly used as the
application name and vendor name for the registry system.
<P>To make use of the registry in your application's code, you can obtain
a reference to the embedded registry object using FXApp::reg(). FXRegistry
provides the following API:
<BR>
<P>FXbool<B> read</B>()
<BR>
<BLOCKQUOTE>This function causes the system-wide registry database to be
read first, followed by the per-user database. In each category,
it reads the Desktop, Vendor, and Application settings in order, overwriting
unmodified settings as it goes.
<BR>Note that upon startup, a FOX application automatically calls the registry's
read() function already. You will usually not call this function,
unless perhaps to re-read the registry.</BLOCKQUOTE>
<P><BR>FXbool<B> write</B>()
<BLOCKQUOTE>If any settings have been changed, this will write out the
changed values into the per-user, per-application files of the registry
database.
<BR>Note that a FOX application automatically calls the registry's write()
function when the application terminates normally (i.e. by calling FXApp::exit()).
You will not call this function under normal conditions, except perhaps
to force changed registry entries to disk, e.g. so that other instances
of the same application will encounter the changed entries, even before
the current one quits.</BLOCKQUOTE>
<P><BR>const FXchar *<B>readStringEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>,const FXchar *<B><I>def</I></B>)
<BLOCKQUOTE>This function attempts to localize the entry <B><I>key</I></B>
in the
<B><I>section</I></B> of the registry database, and returns the
value of this key if it is found; otherwise, it returns the specified <B><I>def</I></B>
value.</BLOCKQUOTE>
<P><BR>FXint <B>readIntEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>,FXint <B><I>def</I></B>)
<BLOCKQUOTE>Similar to the function above, only it assumes the entry's
value is an <I>integer</I> number.
<BR></BLOCKQUOTE>
<P><BR>FXint <B>readUnsignedEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>,FXint <B><I>def</I></B>)
<BLOCKQUOTE>Similar to the function above, only it assumes the entry's
value is an <I>unsigned</I> integer number.
<BR></BLOCKQUOTE>
<P><BR>FXdouble <B>readRealEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>,FXdouble <B><I>def</I></B>)
<BLOCKQUOTE>Assumes that the entry's value is a real number.</BLOCKQUOTE>
<P><BR>FXColor <B>readColorEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>,FXColor <B><I>def</I></B>)
<BLOCKQUOTE>Assumes that the entry's value is a color, which may be specified by a color
name, like "red", or in hex notation, as in "#ff0000".</BLOCKQUOTE>
<P><BR>FXbool <B>writeStringEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>,const FXchar *<B><I>val</I></B>)
<BLOCKQUOTE>Sets or changes the value of <B><I>key</I></B> in the given
<B><I>section
</I></B>to
the value<B><I> val.</I></B> If this key or section does not yet exist,
it is created.</BLOCKQUOTE>
<P><BR>FXbool <B>writeIntEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>,FXint <B><I>val</I></B>)
<BLOCKQUOTE>Similar, but assumes the key's value is an <I>integer</I> number.</BLOCKQUOTE>
<P><BR>FXbool <B>writeUnsignedEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>,FXint <B><I>val</I></B>)
<BLOCKQUOTE>Similar, but assumes the key's value is an <I>unsigned</I>
integer number.</BLOCKQUOTE>
<P><BR>FXbool <B>writeRealEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>,FXdouble <B><I>val</I></B>)
<BLOCKQUOTE>Assumes the entry's value is a real number.</BLOCKQUOTE>
<P><BR>FXbool <B>writeColorEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>,FXColor <B><I>val</I></B>)
<BLOCKQUOTE>Assumes the entry's value is a color; it is translated into a colorname, or
as in hex notation if no name is found for the color.</BLOCKQUOTE>
<P><BR>FXbool <B>deleteEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>)
<BLOCKQUOTE>Removes the entry from the database. It will be removed
from the per-user, per-application file, but not from the system-wide or
per-user Desktop or Vendor files.</BLOCKQUOTE>
<P><BR>FXbool <B>existingEntry</B>(const FXchar *<B><I>section</I></B>,const
FXchar *<B><I>key</I></B>)
<BLOCKQUOTE>Returns true if the given section and key exists.</BLOCKQUOTE>
<P><BR>FXbool <B>deleteSection</B>(const FXchar *<B><I>section</I></B>)
<BR>
<BLOCKQUOTE>Removes the named section from the database. The section will
be removed only from the per-user, per-application file.</BLOCKQUOTE>
<P><BR>FXbool <B>existingSection</B>(const FXchar *<B><I>section</I></B>)
<BLOCKQUOTE>Returns true if the given section exists.</BLOCKQUOTE>
<P><BR>FXbool <B>clear</B>()
<BLOCKQUOTE>Clears the entire database.</BLOCKQUOTE>
<P><BR>void <B>setModified</B>(FXbool <B><I>mdfy</I></B>=TRUE)
<BLOCKQUOTE>Mark the registry as having been modified or non-modified.
One would typically call this to prevent modified entries from being written.</BLOCKQUOTE>
<P><BR>FXbool <B>isModified</B>()
<BLOCKQUOTE>Returns TRUE if the database has been modified.</BLOCKQUOTE>
<P><BR>void <B>setAsciiMode</B>(FXbool <B><I>asciiMode</I></B>)
<BLOCKQUOTE>On MS-Windows, this switches the registry to ASCII based, human-readable
format or, if asciiMode is FALSE, to the binary system.
<BR> </BLOCKQUOTE>
<p>
<p>
<b>The Standard Registry in FOX Application Object</b>
<hr>
Note that the FOX FXApp object provides a registry already. The
standard application registry is defined in terms of the application name
and vendor name that were passed into the FXApp's constructor.
<BR>When an application is started, the standard registry is automatically
loaded when <TT><B>FXApp::init()</B> </TT>is called. Likewise, modified
registry settings are automatically written when <TT><B>FXApp::exit()</B>
</TT>is called. You should take care that these functions are called
when writing your own programs so that settings needed in your program
are available when you expect them, and are properly written back to disk
after the application exits.
<BR>Only changed settings are written back; if no changes have been made
to any settings while running the application, no writing would take place
at all.
<P>You can access the built-in registry object by the <B><TT>FXApp::reg()</TT></B>
member function. For example:
<BLOCKQUOTE>
<PRE><FONT FACE="Courier New,Courier"></FONT></PRE>
<PRE><FONT FACE="Courier New,Courier">FXColor canvasbackground = myapp->reg().readColorEntry("SETTINGS","background",FXRGB(255,255,255));</FONT></PRE>
</BLOCKQUOTE>
<P><BR>To read a background color from the settings database, and default
to white if no entry exists.
<P>When writing the registry, FOX first writes to a temp file, then renames
the temp file to the regular registry file. Since rename() is an
atomic system call, either it works and the new registry is in place, or
it doesn't and the old registry is still in place; at no time would a partially
complete registry file be left behind; therefore, the registry mechanism
should be quite safe even in the presence of multiple applications simultaneously
trying to access the same registry.
<BR>
<P>
<!-- end main window content -->
</td>
<td bgcolor=#ffffff> </td>
<td bgcolor=#557faa width=15> </td>
</tr>
<tr>
<td colspan=2 bgcolor="#557faa" align=center>
</td>
<td bgcolor=#ffffff valign=bottom align=left><img src=art/ill.gif width=8 height=8></td>
<td bgcolor=#ffffff> </td>
<td bgcolor=#ffffff valign=bottom align=right><img src=art/ilr.gif width=8 height=8></td>
<td bgcolor=#557faa width=15> </td>
</tr>
<tr>
<td valign=bottom align=left bgcolor=#557faa><img src=art/oll.gif width=8 height=8></td>
<td colspan=4 bgcolor=#557faa> </td>
<td valign=bottom align=right bgcolor=#557faa><img src=art/olr.gif width=8 height=8></td>
</tr>
</table>
<address>Copyright 1997-2002 <a href=mailto:jeroen@fox-toolkit.org>Jeroen van der Zijp</a></address>
<!-- Created: Mon Apr 10 11:20:32 CEST 2000 -->
<!-- hhmts start -->
<!-- hhmts end -->
</body>
</html>
