![]() ![]() |
![]() |
||||||||||
![]() |
![]() |
||||||||||
Home News Download Goals & Approach Documentation FAQ Screenshots Adie PathFinder FOX Calculator Projects FXPy FXRuby EiffelFox The FOX Hole Japanese Docs ![]() |
![]() Documentation: The FOX Registry
What is a Registry? 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. 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. 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. 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).
Design Features of the FOX Registry 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. Tallying it all up, I've come up with the following list of requirements
for a registry system:
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. 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 never written, except perhaps when the application is being installed. 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:
The same directory structure applies for both system-wide settings and per-user settings. The system-wide settings are found in directories: /etc/foxrcPer-user settings are found in: $HOME/.foxrcWhich is a hidden directory directly under the users regular HOME directory.
Format of a Registry File 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. For example:
# A section
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.
Using the Registry 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(). The application name and vendor name parameters passed in when you construct the FXApp object are directly used as the application name and vendor name for the registry system. 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:
FXbool read()
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.
If any settings have been changed, this will write out the changed values into the per-user, per-application files of the registry database.
This function attempts to localize the entry key in the section of the registry database, and returns the value of this key if it is found; otherwise, it returns the specified def value.
Similar to the function above, only it assumes the entry's value is an integer number.
Similar to the function above, only it assumes the entry's value is an unsigned integer number.
Assumes that the entry's value is a real number.
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".
Sets or changes the value of key in the given section to the value val. If this key or section does not yet exist, it is created.
Similar, but assumes the key's value is an integer number.
Similar, but assumes the key's value is an unsigned integer number.
Assumes the entry's value is a real number.
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.
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.
Returns true if the given section and key exists.
Removes the named section from the database. The section will be removed only from the per-user, per-application file.
Returns true if the given section exists.
Clears the entire database.
Mark the registry as having been modified or non-modified. One would typically call this to prevent modified entries from being written.
Returns TRUE if the database has been modified.
On MS-Windows, this switches the registry to ASCII based, human-readable format or, if asciiMode is FALSE, to the binary system.
The Standard Registry in FOX Application Object 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. When an application is started, the standard registry is automatically loaded when FXApp::init() is called. Likewise, modified registry settings are automatically written when FXApp::exit() 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. 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. You can access the built-in registry object by the FXApp::reg() member function. For example: FXColor canvasbackground = myapp->reg().readColorEntry("SETTINGS","background",FXRGB(255,255,255));
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.
|
||||||||||
![]() |
![]() |
||||||||||
![]() |
![]() |