Fl_Preferences 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.
Fl_Preferences uses a hierarchy to store data. It bundles similar data into groups and manages entries into those groups as name/value pairs.
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.
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 getUserdataPath() method.
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.
The first format creates the base 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.
The second format is used to create a preferences file at an arbitrary position in the file system. The file name is generated as path/application.prefs. If application is 0, path must contain the full file name.
The third format generates a new group of preference entries inside the group or file p. The groupname argument identifies a group of entries. It can contain '/'s to get quick access to individual elements inside the hierarchy.
The destructor removes allocated resources. When used on the base preferences group, the destructor flushes all changes to the preferences file and deletes all internal databases.
Removes a single entry (name/value pair).
Deletes a group.
Returns the number of entries (name/value) pairs in a group.
Returns the name of an entry. There is no guaranteed order of entry names. The index must be within the range given by entries().
Returns non-zero if an entry with this name exists.
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.
Creates a path that is related to the preferences file and that is usable for application data beyond what is covered by Fl_Preferences.
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 'char *&text' or 'void *&data' form is used, the resulting data must be freed with 'free(value)'.
'maxLength' is the maximum length of text that will be read. The text buffer must allow for one additional byte for a trailling zero.
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().
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.
Returns the number of groups that are contained within a group.
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.
Returns the size of the value part of an entry.
'Name' provides a simple method to create numerical or more complex procedural names for entries and groups on the fly, i.e. prefs.set(Fl_Preferences::Name("File%d",i),file[i]);. See test/preferences.cxx as a sample for writing arrays into preferences.
'Name' is actually implemented as a class inside Fl_Preferences. It casts into const char* and gets automatically destroyed after the enclosing call.