class Fl_Preferences

Class Hierarchy

Include Files

Description

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.

Methods

Fl_Preferences(enum Root root, const char *vendor, const char *application)
Fl_Preferences(const char *path, const char *vendor, const char *application)
Fl_Preferences(Fl_Preferences &p, const char *groupname)

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.

~Fl_Preferences()

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.

int Fl_Preferences::deleteEntry(const char *entry)

Removes a single entry (name/value pair).

int Fl_Preferences::deleteGroup(const char *groupname)

Deletes a group.

int Fl_Preferences::entries()

Returns the number of entries (name/value) pairs in a group.

const char *Fl_Preferences::entry(int 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().

int Fl_Preferences::entryExists(const char *entry)

Returns non-zero if an entry with this name exists.

void Fl_Preferences::flush()

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.

int Fl_Preferences::getUserdataPath(char *path, int path_size)

Creates a path that is related to the preferences file and that is usable for application data beyond what is covered by Fl_Preferences.

int get(const char *entry, int &value, int defaultValue)
int get(const char *entry, int &value, int defaultValue)
int get(const char *entry, float &value, float defaultValue)
int get(const char *entry, double &value, double defaultValue )
int get(const char *entry, char *&text, const char *defaultValue)
int get(const char *entry, char *text, const char *defaultValue, int maxLength)
int get(const char *entry, void *&data, const void *defaultValue, int defaultSize)
int get(const char *entry, void *data, const void *defaultValue, int defaultSize, int maxSize)

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.

const char *Fl_Preferences::group(int 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().

int Fl_Preferences::groupExists(const char *groupname)

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.

int Fl_Preferences::groups()

Returns the number of groups that are contained within a group.

int set(const char *entry, int value)
int set(const char *entry, int value)
int set(const char *entry, float value)
int set(const char *entry, double value)
int set(const char *entry, const char *text)
int set(const char *entry, const void *data, int size)

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.

int Fl_Preferences::size(const char *key)

Returns the size of the value part of an entry.

Fl_Preferences::Name( unsigned int numericName )
Fl_Preferences::Name( const char *format, ... )

'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.