Fl_Preferences provides methods to store user settings between application starts. More...

#include <Fl_Preferences.H>

Inheritance diagram for Fl_Preferences:

Collaboration diagram for Fl_Preferences:

Classes
struct	Entry
class	Name
class	Node
class	RootNode
Public Types
enum	Root { SYSTEM = 0, USER }
typedef void *	ID
Public Member Functions
	Fl_Preferences (Root root, const char vendor, const char application)
	Fl_Preferences (const char path, const char vendor, const char *application)
	Use this constructor to create or read a preferences file at an arbitrary position in the file system.
	Fl_Preferences (Fl_Preferences &parent, const char *group)
	Generate or read a new group of entries within another group.
	Fl_Preferences (Fl_Preferences parent, const char group)
	Create or access a group of preferences using a name.
	Fl_Preferences (Fl_Preferences &parent, int groupIndex)
	Open a child group using a given index.
	Fl_Preferences (Fl_Preferences *parent, int groupIndex)
	Fl_Preferences (const Fl_Preferences &)
	Fl_Preferences (ID id)
virtual	~Fl_Preferences ()
ID	id ()
const char *	name ()
const char *	path ()
int	groups ()
const char *	group (int num_group)
char	groupExists (const char *key)
char	deleteGroup (const char *group)
char	deleteAllGroups ()
int	entries ()
const char *	entry (int index)
char	entryExists (const char *key)
char	deleteEntry (const char *entry)
char	deleteAllEntries ()
char	clear ()
char	set (const char *entry, int value)
char	set (const char *entry, float value)
char	set (const char *entry, float value, int precision)
char	set (const char *entry, double value)
char	set (const char *entry, double value, int precision)
char	set (const char entry, const char value)
char	set (const char entry, const void value, int size)
char	get (const char *entry, int &value, int defaultValue)
char	get (const char *entry, float &value, float defaultValue)
char	get (const char *entry, double &value, double defaultValue)
char	get (const char entry, char &value, const char *defaultValue)
char	get (const char entry, char value, const char *defaultValue, int maxSize)
char	get (const char entry, void &value, const void *defaultValue, int defaultSize)
char	get (const char entry, void value, const void *defaultValue, int defaultSize, int maxSize)
int	size (const char *entry)
char	getUserdataPath (char *path, int pathlen)
	Creates a path that is related to the preferences file and that is usable for additional application data.
void	flush ()
Static Public Member Functions
static const char *	newUUID ()
static char	remove (ID id_)
Protected Attributes
Node *	node
RootNode *	rootNode
Friends
class	Node
class	RootNode

Detailed Description

Fl_Preferences provides methods to store user settings 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 small for performance reasons. One application can have multiple preferences files. Extensive binary data however should be stored in separate files: see getUserdataPath().

Note:: Starting with FLTK 1.3, preference databases are expected to be in utf8 encoding. Previous databases were stored in the current chracter set or code page which renders them incompatible for text entries using international characters.

Definition at line 69 of file Fl_Preferences.H.

Member Typedef Documentation

typedef void* Fl_Preferences::ID

Every Fl_Preferences-Group has a uniqe ID.

ID's can be retrieved from an Fl_Preferences-Group and can then be used to create more Fl_Preference references to the same data set, as long as the database remains open.

Definition at line 87 of file Fl_Preferences.H.

Member Enumeration Documentation

enum Fl_Preferences::Root

Define the scope of the preferences.

Enumerator:

SYSTEM	Preferences are used system-wide.
USER	Preferences apply only to the current user.

Definition at line 75 of file Fl_Preferences.H.

Constructor & Destructor Documentation

Fl_Preferences::Fl_Preferences	(	Root	root,
		const char *	vendor,
		const char *	application
	)

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.

This constructor 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.

A set of Preferences marked "run-time" exists exactly one per application and only as long as the application runs. It can be used as a database for volatile information. FLTK uses it to register plugins at run-time.

Parameters:

[in]	root	can be `USER` or `SYSTEM` for user specific or system wide preferences
[in]	vendor	unique text describing the company or author of this file
[in]	application	unique text describing the application

Definition at line 237 of file Fl_Preferences.cxx.

References Fl_Preferences(), Node, node, RootNode, and rootNode.

Referenced by Fl_Preferences().

Fl_Preferences::Fl_Preferences	(	const char *	path,
		const char *	vendor,
		const char *	application
	)

Use this constructor to create or read a preferences file at an arbitrary position in the file system.

The file name is generated in the form path/application.prefs. If application is NULL, path must contain the full file name.

Parameters:

[in]	path	path to the directory that contains the preferences file
[in]	vendor	unique text describing the company or author of this file
[in]	application	unique text describing the application

Definition at line 255 of file Fl_Preferences.cxx.

References Fl_Preferences(), Node, node, RootNode, and rootNode.

Fl_Preferences::Fl_Preferences	(	Fl_Preferences &	parent,
		const char *	group
	)

Generate or read a new group of entries within another group.

Use the group argument to name the group that you would like to access. Group can also contain a path to a group further down the hierarchy by separating group names with a forward slash '/'.

Parameters:

[in]	parent	reference object for the new group
[in]	group	name of the group to access (may contain '/'s)

Definition at line 271 of file Fl_Preferences.cxx.

References Fl_Preferences(), node, and rootNode.

Fl_Preferences::Fl_Preferences	(	Fl_Preferences *	parent,
		const char *	group
	)

Create or access a group of preferences using a name.

Parameters:

[in]	parent	the parameter parent is a pointer to the parent group. `Parent` may be `NULL`. It then refers to an application internal database which exists only once, and remains in RAM only until the application quits. This database is used to manage plugins and other data indexes by strings.
[in]	group	a group name that is used as a key into the database

See also:: Fl_Preferences( Fl_Preferences&, const char *group )

Definition at line 286 of file Fl_Preferences.cxx.

References Fl_Preferences(), Node, node, RootNode, and rootNode.

Fl_Preferences::Fl_Preferences	(	Fl_Preferences &	parent,
		int	groupIndex
	)

Open a child group using a given index.

Use the groupIndex argument to find the group that you would like to access. If the given index is invalid (negative or too high), a new group is created with a UUID as a name.

The index needs to be fixed. It is currently backward. Index 0 points to the last member in the 'list' of preferences.

Parameters:

[in]	parent	reference object for the new group
[in]	groupIndex	zero based index into child groups

Definition at line 313 of file Fl_Preferences.cxx.

References Fl_Preferences(), groups(), newUUID(), node, and rootNode.

Fl_Preferences::Fl_Preferences	(	Fl_Preferences *	parent,
		int	groupIndex
	)

See also:: Fl_Preferences( Fl_Preferences&, int groupIndex )

Definition at line 325 of file Fl_Preferences.cxx.

References Fl_Preferences(), groups(), newUUID(), node, and rootNode.

Fl_Preferences::Fl_Preferences ( const Fl_Preferences & rhs )

Create another reference to a Preferences group.

Definition at line 353 of file Fl_Preferences.cxx.

References Fl_Preferences().

Fl_Preferences::Fl_Preferences ( Fl_Preferences::ID id )

Create a new dataset access point using a dataset ID.

ID's are a great way to remember shortcuts to database entries that are deeply nested in a preferences database, as long as the database root is not deleted. An ID can be retrieved from any Fl_Preferences dataset, and can then be used to create multiple new references to the same dataset.

ID's can be put very helpful when put into the user_data() field of widget callbacks.

Definition at line 345 of file Fl_Preferences.cxx.

References Fl_Preferences(), Node, node, and rootNode.

Fl_Preferences::~Fl_Preferences ( ) [virtual]

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.

The destructor does not remove any data from the database. It merely deletes your reference to the database.

Definition at line 378 of file Fl_Preferences.cxx.

References node, and rootNode.

Member Function Documentation

char Fl_Preferences::clear ( )

Delete all groups and all entries.

Definition at line 498 of file Fl_Preferences.cxx.

References deleteAllEntries(), and deleteAllGroups().

char Fl_Preferences::deleteAllEntries ( )

Delete all entries.

Definition at line 490 of file Fl_Preferences.cxx.

References node.

Referenced by clear().

char Fl_Preferences::deleteAllGroups ( )

Delete all groups.

Definition at line 439 of file Fl_Preferences.cxx.

References node.

Referenced by clear().

char Fl_Preferences::deleteEntry ( const char * key )

Deletes a single name/value pair.

This function removes the entry key from the database.

Parameters:

[in] key name of entry to delete

Returns:: 0 if deleting the entry failed

Definition at line 483 of file Fl_Preferences.cxx.

References node.

Referenced by Fl_Comment_Type::open().

char Fl_Preferences::deleteGroup ( const char * group )

Deletes a group.

Removes a group and all keys and groups within that group from the database.

Parameters:

[in] group name of the group to delete

Returns:: 0 if call failed

Definition at line 430 of file Fl_Preferences.cxx.

References node, and Node.

int Fl_Preferences::entries ( )

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

Returns:: number of entries

Definition at line 449 of file Fl_Preferences.cxx.

References node.

Referenced by Fl_Tree::load().

const char * Fl_Preferences::entry ( int index )

Returns the name of an entry. There is no guaranteed order of entry names. The index must be within the range given by entries().

Parameters:

[in] index number indexing the requested entry

Returns:: pointer to value cstring

Definition at line 461 of file Fl_Preferences.cxx.

References node.

Referenced by Fl_Tree::load().

char Fl_Preferences::entryExists ( const char * key )

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

Parameters:

[in] key name of entry that is searched for

Returns:: 0 if entry was not found

Definition at line 471 of file Fl_Preferences.cxx.

References node.

void Fl_Preferences::flush ( )

Writes all preferences to disk. This function works only with the base preferences group. This function is rarely used as deleting the base preferences flushes automatically.

Definition at line 901 of file Fl_Preferences.cxx.

References node, and rootNode.

Referenced by Fl_File_Chooser::preview().

char Fl_Preferences::get	(	const char *	key,
		char *&	text,
		const char *	defaultValue
	)

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). get() allocates memory of sufficient size to hold the value. The buffer must be free'd by the developer using 'free(value)'.

Parameters:

[in]	key	name of entry
[out]	text	returned from preferences or default value if none was set
[in]	defaultValue	default value to be used if no preference was set

Returns:: 0 if the default value was used

Definition at line 703 of file Fl_Preferences.cxx.

References node.

char Fl_Preferences::get	(	const char *	key,
		int &	value,
		int	defaultValue
	)

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

Parameters:

[in]	key	name of entry
[out]	value	returned from preferences or default value if none was set
[in]	defaultValue	default value to be used if no preference was set

Returns:: 0 if the default value was used

Definition at line 514 of file Fl_Preferences.cxx.

References node.

Referenced by Fl_File_Chooser::Fl_File_Chooser(), Fl_Tree::load(), load_history(), make_main_window(), make_settings_window(), make_shell_window(), Fl_Comment_Type::open(), Fl::option(), Fl_Plugin_Manager::plugin(), position_window(), print_update_status(), Fl_File_Chooser::rescan_keep_filename(), toggle_sourceview_cb(), and update_history().

char Fl_Preferences::get	(	const char *	key,
		float &	value,
		float	defaultValue
	)

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

Parameters:

[in]	key	name of entry
[out]	value	returned from preferences or default value if none was set
[in]	defaultValue	default value to be used if no preference was set

Returns:: 0 if the default value was used

Definition at line 546 of file Fl_Preferences.cxx.

References node.

char Fl_Preferences::get	(	const char *	key,
		double &	value,
		double	defaultValue
	)

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

Parameters:

[in]	key	name of entry
[out]	value	returned from preferences or default value if none was set
[in]	defaultValue	default value to be used if no preference was set

Returns:: 0 if the default value was used

Definition at line 595 of file Fl_Preferences.cxx.

References node.

char Fl_Preferences::get	(	const char *	key,
		char *	text,
		const char *	defaultValue,
		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). 'maxSize' is the maximum length of text that will be read. The text buffer must allow for one additional byte for a trailling zero.

Parameters:

[in]	key	name of entry
[out]	text	returned from preferences or default value if none was set
[in]	defaultValue	default value to be used if no preference was set
[in]	maxSize	maximum length of value plus one byte for a trailing zero

Returns:: 0 if the default value was used

Definition at line 677 of file Fl_Preferences.cxx.

References node, strlcpy, and w.

char Fl_Preferences::get	(	const char *	key,
		void *&	data,
		const void *	defaultValue,
		int	defaultSize
	)

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). get() allocates memory of sufficient size to hold the value. The buffer must be free'd by the developer using 'free(value)'.

Parameters:

[in]	key	name of entry
[out]	data	returned from preferences or default value if none was set
[in]	defaultValue	default value to be used if no preference was set
[in]	defaultSize	size of default value array

Returns:: 0 if the default value was used

Definition at line 810 of file Fl_Preferences.cxx.

References node.

char Fl_Preferences::get	(	const char *	key,
		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). 'maxSize' is the maximum length of text that will be read.

Parameters:

[in]	key	name of entry
[out]	data	value returned from preferences or default value if none was set
[in]	defaultValue	default value to be used if no preference was set
[in]	defaultSize	size of default value array
[in]	maxSize	maximum length of value

Returns:: 0 if the default value was used

Todo:: maxSize should receive the number of bytes that were read.

Definition at line 783 of file Fl_Preferences.cxx.

References node, and w.

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

Creates a path that is related to the preferences file and that is usable for additional application data.

This function creates a directory that is named after the preferences database without the .prefs extension and located in the same directory. It then fills the given buffer with the complete path name.

Exmaple:

 Fl_Preferences prefs( USER, "matthiasm.com", "test" );
 char path[FL_PATH_MAX];
 prefs.getUserdataPath( path );

creates the preferences database in (MS Windows):

 c:/Documents and Settings/matt/Application Data/matthiasm.com/test.prefs

and returns the userdata path:

 c:/Documents and Settings/matt/Application Data/matthiasm.com/test/

Parameters:

[out]	path	buffer for user data path
[in]	pathlen	size of path buffer (should be at least `FL_PATH_MAX`)

Returns:: 0 if path was not created or pathname can't fit into buffer

Definition at line 890 of file Fl_Preferences.cxx.

References rootNode.

Referenced by save_template_cb(), template_load(), and update_sourceview_cb().

const char * Fl_Preferences::group ( int num_group )

Returns the name of the Nth (num_group) group. There is no guaranteed order of group names. The index must be within the range given by groups().

Parameters:

[in] num_group number indexing the requested group

Returns:: 'C' string pointer to the group name

Definition at line 404 of file Fl_Preferences.cxx.

References node.

char Fl_Preferences::groupExists ( const char * key )

Returns non-zero if a group with this name exists. Group names 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.

Parameters:

[in] key name of group that is searched for

Returns:: 0 if no group by that name was found

Definition at line 417 of file Fl_Preferences.cxx.

References node.

Referenced by Fl_Plugin_Manager::plugin().

int Fl_Preferences::groups ( )

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

Returns:: 0 for no groups at all

Definition at line 392 of file Fl_Preferences.cxx.

References node.

Referenced by Fl_Preferences(), Fl_Tree::load(), and Fl_Plugin_Manager::plugins().

ID Fl_Preferences::id ( ) [inline]

Return an ID that can later be reused to open more references to this dataset.

Definition at line 103 of file Fl_Preferences.H.

Referenced by Fl_Plugin_Manager::addPlugin().

const char* Fl_Preferences::name ( ) [inline]

Return the name of this entry.

Definition at line 111 of file Fl_Preferences.H.

Referenced by newUUID().

const char * Fl_Preferences::newUUID ( ) [static]

Returns a UUID as generated by the system.

A UUID is a "universally unique identifier" which is commonly used in configuration files to create identities. A UUID in ASCII looks like this: 937C4900-51AA-4C11-8DD3-7AB59944F03E. It has always 36 bytes plus a trailing zero.

Returns:: a pointer to a static buffer containing the new UUID in ASCII format. The buffer is overwritten during every call to this function!

Definition at line 87 of file Fl_Preferences.cxx.

References b, name(), and NULL.

Referenced by Fl_Preferences().

const char* Fl_Preferences::path ( ) [inline]

Return the the full path to this entry.

Definition at line 115 of file Fl_Preferences.H.

Referenced by Fl_Tree::load().

static char Fl_Preferences::remove ( ID id_ ) [inline, static]

Remove the group with this ID from a database.

Definition at line 107 of file Fl_Preferences.H.

Referenced by Fl_Plugin_Manager::removePlugin(), and Fl_Plugin::~Fl_Plugin().

char Fl_Preferences::set	(	const char *	key,
		float	value
	)

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.

Parameters:

[in]	key	name of entry
[in]	value	set this entry to `value`

Returns:: 0 if setting the value failed

Definition at line 562 of file Fl_Preferences.cxx.

References node.

char Fl_Preferences::set	(	const char *	key,
		double	value,
		int	precision
	)

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.

Parameters:

[in]	key	name of entry
[in]	value	set this entry to `value`
[in]	precision	number of decimal digits to represent value

Returns:: 0 if setting the value failed

Definition at line 628 of file Fl_Preferences.cxx.

References node.

char Fl_Preferences::set	(	const char *	key,
		double	value
	)

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.

Parameters:

[in]	key	name of entry
[in]	value	set this entry to `value`

Returns:: 0 if setting the value failed

Definition at line 611 of file Fl_Preferences.cxx.

References node.

char Fl_Preferences::set	(	const char *	key,
		const char *	text
	)

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.

Parameters:

[in]	key	name of entry
[in]	text	set this entry to `value`

Returns:: 0 if setting the value failed

Definition at line 727 of file Fl_Preferences.cxx.

References buffer, and node.

char Fl_Preferences::set	(	const char *	key,
		const void *	data,
		int	dsize
	)

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.

Parameters:

[in]	key	name of entry
[in]	data	set this entry to `value`
[in]	dsize	size of data array

Returns:: 0 if setting the value failed

Definition at line 837 of file Fl_Preferences.cxx.

References buffer, and node.

char Fl_Preferences::set	(	const char *	key,
		int	value
	)

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.

Parameters:

[in]	key	name of entry
[in]	value	set this entry to `value`

Returns:: 0 if setting the value failed

Definition at line 530 of file Fl_Preferences.cxx.

References node.

Referenced by Fl_Plugin_Manager::addPlugin(), default_widget_size_cb(), exit_cb(), grid_cb(), guides_cb(), Fl_Comment_Type::open(), Fl_File_Chooser::preview(), save_position(), scheme_cb(), and update_history().

char Fl_Preferences::set	(	const char *	key,
		float	value,
		int	precision
	)

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.

Parameters:

[in]	key	name of entry
[in]	value	set this entry to `value`
[in]	precision	number of decimal digits to represent value

Returns:: 0 if setting the value failed

Definition at line 579 of file Fl_Preferences.cxx.

References node.

int Fl_Preferences::size ( const char * key )

Returns the size of the value part of an entry.

Parameters:

[in] key name of entry

Returns:: size of value

Definition at line 858 of file Fl_Preferences.cxx.

References node.

Friends And Related Function Documentation

friend class Node [friend]

Definition at line 250 of file Fl_Preferences.H.

Referenced by deleteGroup(), and Fl_Preferences().

friend class RootNode [friend]

Definition at line 265 of file Fl_Preferences.H.

Referenced by Fl_Preferences().

Member Data Documentation

Node* Fl_Preferences::node [protected]

Definition at line 268 of file Fl_Preferences.H.

Referenced by deleteAllEntries(), deleteAllGroups(), deleteEntry(), deleteGroup(), entries(), entry(), entryExists(), Fl_Preferences(), flush(), get(), group(), groupExists(), groups(), set(), size(), and ~Fl_Preferences().

RootNode* Fl_Preferences::rootNode [protected]

Definition at line 269 of file Fl_Preferences.H.

Referenced by Fl_Preferences(), flush(), getUserdataPath(), and ~Fl_Preferences().

The documentation for this class was generated from the following files:

fltk-1.3.0rc3/FL/Fl_Preferences.H
fltk-1.3.0rc3/src/Fl_Preferences.cxx

Fl_Preferences Class Reference

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation