FLTK 1.4.4: Fl_Preferences Class Reference

FLTK 1.4.4

Loading...
Searching...
No Matches
Fl_Preferences Class Reference

Fl_Preferences store user settings between application starts. More...

`#include <Fl_Preferences.H>`

Inheritance diagram for Fl_Preferences:

## Classes
struct | Entry
class | Name
| 'Name' provides a simple method to create numerical or more complex procedural names for entries and groups on the fly. More...
class | Node
class | RootNode

## Public Types
typedef void * | ID
| Every Fl_Preferences-Group has a unique ID.
enum | Root { UNKNOWN_ROOT_TYPE = -1 , SYSTEM = 0 , USER , MEMORY , ROOT_MASK = 0x00FF , CORE = 0x0100 , C_LOCALE = 0x1000 , CLEAR = 0x2000 , SYSTEM_L = SYSTEM | C_LOCALE , USER_L = USER | C_LOCALE , CORE_SYSTEM_L = CORE | SYSTEM_L , CORE_USER_L = CORE | USER_L , CORE_SYSTEM = CORE | SYSTEM , CORE_USER = CORE | USER }
| Define the scope of the preferences. More...

## Public Member Functions
char | clear ()
| Delete all groups and all entries.
char | delete_all_entries ()
| Delete all entries.
char | delete_all_groups ()
| Delete all groups.
char | delete_entry (const char *entry)
| Deletes a single name/value pair.
char | delete_group (const char *group)
| Deletes a group.
int | dirty ()
| Check if there were changes to the database that need to be written to disk.
int | entries ()
| Returns the number of entries (name/value pairs) in a group.
const char * | entry (int index)
| Returns the name of an entry.
char | entry_exists (const char *key)
| Returns non-zero if an entry with this name exists.
Root | filename (char *buffer, size_t buffer_size)
| Return the file name and path to the preference file.
| Fl_Preferences (const char *path, const char *vendor, const char *application)
| Deprecated: Use this constructor to create or read a preference file at an arbitrary position in the file system.
| Fl_Preferences (const char *path, const char *vendor, const char *application, Root flags)
| Use this constructor to create or read a preference file at an arbitrary position in the file system.
| Fl_Preferences (const Fl_Preferences &)
| Create another reference to a Preferences group.
| Fl_Preferences (Fl_Preferences &parent, const char *group)
| Generate or read a new group of entries within another group.
| Fl_Preferences (Fl_Preferences &parent, int groupIndex)
| Open a child group using a given index.
| 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)
| Fl_Preferences (ID id)
| Create a new dataset access point using a dataset ID.
| Fl_Preferences (Root root, const char *vendor, const char *application)
| The constructor creates a group that manages key/value pairs and child groups.
int | flush ()
| Writes preferences to disk if they were modified.
char | get (const char *entry, char *&value, const char *defaultValue)
| Reads an entry from the group.
char | get (const char *entry, char *value, const char *defaultValue, int maxSize)
| Reads an entry from the group.
char | get (const char *entry, double &value, double defaultValue)
| Reads an entry from the group.
char | get (const char *entry, float &value, float defaultValue)
| Reads an entry from the group.
char | get (const char *entry, int &value, int defaultValue)
| Reads an entry from the group.
char | get (const char *entry, void *&value, const void *defaultValue, int defaultSize)
| Reads an entry from the group.
char | get (const char *entry, void *value, const void *defaultValue, int defaultSize, int *size)
| Reads a binary entry from the group, encoded in hexadecimal blocks.
char | get (const char *entry, void *value, const void *defaultValue, int defaultSize, int maxSize)
| Reads a binary entry from the group, encoded in hexadecimal blocks.
char | get_userdata_path (char *path, int pathlen)
| Creates a path that is related to the preference file and that is usable for additional application data.
const char * | group (int num_group)
| Returns the name of the Nth (`num_group`) group.
char | group_exists (const char *key)
| Returns non-zero if a group with this name exists.
int | groups ()
| Returns the number of groups that are contained within a group.
ID | id ()
| Return an ID that can later be reused to open more references to this dataset.
const char * | name ()
| Return the name of this entry.
const char * | path ()
| Return the full path to this entry.
char | set (const char *entry, const char *value)
| Sets an entry (name/value pair).
char | set (const char *entry, const void *value, int size)
| Sets an entry (name/value pair).
char | set (const char *entry, double value)
| Sets an entry (name/value pair).
char | set (const char *entry, double value, int precision)
| Sets an entry (name/value pair).
char | set (const char *entry, float value)
| Sets an entry (name/value pair).
char | set (const char *entry, float value, int precision)
| Sets an entry (name/value pair).
char | set (const char *entry, int value)
| Sets an entry (name/value pair).
int | size (const char *entry)
| Returns the size of the value part of an entry.
virtual | ~Fl_Preferences ()
| The destructor removes allocated resources.

## Static Public Member Functions
static unsigned int | file_access ()
| Return the current file access permissions for the FLTK preferences system.
static void | file_access (unsigned int flags)
| Tell the FLTK preferences system which files in the file system it may read, create, or write.
static Root | filename (char *buffer, size_t buffer_size, Root root, const char *vendor, const char *application)
| Determine the file name and path to preferences that would be opened with these parameters.
static const char * | new_UUID ()
| Returns a UUID as generated by the system.
static char | remove (ID id_)
| Remove the group with this ID from a database.

## Static Public Attributes
static const unsigned int | ALL = ALL_READ_OK | ALL_WRITE_OK
| Set this to give FLTK and applications permission to read, write, and create preference files.
static const unsigned int | ALL_READ_OK = USER_READ_OK | SYSTEM_READ_OK | CORE_READ_OK
| Set this to allow FLTK and applications to read preference files.
static const unsigned int | ALL_WRITE_OK = USER_WRITE_OK | SYSTEM_WRITE_OK | CORE_WRITE_OK
| Set this to allow FLTK and applications to create and write preference files.
static const unsigned int | APP_OK = SYSTEM_OK | USER_OK
| Set this if it is OK for applications to read, create, and write any kind of preference files.
static const unsigned int | CORE_OK = CORE_READ_OK | CORE_WRITE_OK
| Set this if it is OK for FLTK to read, create, or write preference files.
static const unsigned int | CORE_READ_OK = 0x0010
| Set this if it is OK for FLTK to read preference files.
static const unsigned int | CORE_WRITE_OK = 0x0020
| Set this if it is OK for FLTK to create or write preference files.
static const unsigned int | NONE = 0x0000
| Set this if no call to Fl_Preferences shall access the file system.
static const unsigned int | SYSTEM_OK = SYSTEM_READ_OK | SYSTEM_WRITE_OK
| Set this if it is OK for applications to read, create, and write system wide preference files.
static const unsigned int | SYSTEM_READ_OK = 0x0004
| Set this if it is OK for applications to read system wide preference files.
static const unsigned int | SYSTEM_WRITE_OK = 0x0008
| Set this if it is OK for applications to create and write system wide preference files.
static const unsigned int | USER_OK = USER_READ_OK | USER_WRITE_OK
| Set this if it is OK for applications to read, create, and write user preference files.
static const unsigned int | USER_READ_OK = 0x0001
| Set this if it is OK for applications to read user preference files.
static const unsigned int | USER_WRITE_OK = 0x0002
| Set this if it is OK for applications to create and write user preference files.

## Protected Attributes
Node * | node
RootNode * | rootNode

## Friends
class | Node
class | RootNode

## Detailed Description

Fl_Preferences store user settings between application starts.

FLTK Preferences are similar to the Registry on Windows and Preferences on MacOS, providing a simple method to store customizable user settings between application launches. A typical use is storing the last window position or a history of previously used documents.

Preferences are organized in a hierarchy of groups. Every group can contain more groups and any number of key/value pairs. Keys can be text strings containing ASCII letters, digits, periods, and underscores. Forward slashes in a key name are treated as subgroups, i.e. the key 'window/width' would actually refer to the key 'width' inside the group 'window'.

Keys have a unique name within their group. A value can be any string including control characters 0x00 to 0x1f, 0x7f, and UTF-8 octets.

Several methods allow setting and getting numerical values and binary data.

Preferences files are the same across platforms. User comments in preference files are preserved. Filenames are unique for each application by using a vendor/application naming scheme. The developer app must provide default values for all entries to ensure proper operation should preferences be corrupted or not yet exist.

Note
  The format of preferences files is not part of the FLTK specification and intentionally undocumented. The only valid way to read or write prefs files is via the API from your app. The fact that the current implementation looks like human-readable text is purely coincidental and may change at any time. Preferences files are not meant to be created or edited "by hand."

FLTK preferences are not meant to replace a fully featured database. No merging of data takes place. If several instances of an app access the same database at the same time, only the most recent changes will persist.

Preferences should not be used to store document data. The .prefs 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 Fl_Preferences::get_userdata_path() .

Fl_Preferences are not thread-safe. They can temporarily change the locale on some platforms during read and write access, which also changes it temporarily in other threads of the same app.

Typically a preferences database is read at startup, and then reopened and written at app shutdown:

int appWindowWidth, appWindowHeight;
void launch() {
Fl_Preferences app(Fl_Preferences::USER_L, "matthiasm.com", "hello");
// 'app' constructor will be called, reading data from .prefs file
Fl_Preferences window(app, "window");
window.get("width", appWindowWidth, 800);
window.get("height", appWindowHeight, 600);
// 'app' destructor will be called. This will write data to the
// .prefs file if any preferences were changed or added
}
void quit() {
Fl_Preferences app(Fl_Preferences::USER_L, "matthiasm.com", "hello");
Fl_Preferences window(app, "window");
window.set("width", appWindowWidth);
window.set("height", appWindowHeight);
}
Fl_Preferences
Fl_Preferences store user settings between application starts.
Definition Fl_Preferences.H:125
Fl_Preferences::USER_L
@ USER_L
Preferences apply only to the current user, locale independent.
Definition Fl_Preferences.H:142
Fl_Preferences::Fl_Preferences
Fl_Preferences(Root root, const char *vendor, const char *application)
The constructor creates a group that manages key/value pairs and child groups.
Definition Fl_Preferences.cxx:365

See also
  Fl_Preferences::Fl_Preferences(Root root, const char *vendor, const char *application)
  As a special case, Fl_Preferences can be memory mapped and not be associated with a file on disk. See Fl_Preferences::Fl_Preferences(Fl_Preferences *parent, const char *group) and Fl_Preferences::MEMORY for more details on memory mapped preferences.

Note
  Starting with FLTK 1.3, preferences databases are expected to be in UTF-8 encoding. Previous databases were stored in the current character set or code page which renders them incompatible for text entries using international characters.
  Starting with FLTK 1.4, searching a valid path to store the preference files has changed slightly. Please see Fl_Preferences::Fl_Preferences(Root, const char*, const char*) for details.
  Starting with FLTK 1.4, preference files should be created with SYSTEM_L or USER_L to be interchangeable between computers with differing locale settings. The legacy modes, LOCAL and SYSTEM, will read and write floating point values using the decimal point of the current locale. As a result, a fp-value would be written '3,1415' on a German machine, and would be read back as '3.0' on a US machine because the comma would not be recognized as an alternative decimal point.

## Member Typedef Documentation

## ◆ ID

typedef void* Fl_Preferences::ID

Every Fl_Preferences-Group has a unique 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.

## Member Enumeration Documentation

## ◆ Root

enum Fl_Preferences::Root

Define the scope of the preferences.

Enumerator
UNKNOWN_ROOT_TYPE | Returned if storage could not be determined.
SYSTEM | Preferences are used system-wide. Deprecated, see SYSTEM_L.
USER | Preferences apply only to the current user. Deprecated, see USER_L.
MEMORY | Returned if querying memory mapped preferences.
ROOT_MASK | Mask for the values above.
CORE | OR'd by FLTK to read and write core library preferences and options.
C_LOCALE | This flag should always be set to ensure that floating point values are written and read correctly independently of the current locale.
CLEAR | Don't read a possibly existing database. Instead, start with an empty set of preferences.
SYSTEM_L | Preferences are used system-wide, locale independent.
USER_L | Preferences apply only to the current user, locale independent.
CORE_SYSTEM_L | Same as CORE | SYSTEM | C_LOCALE.
CORE_USER_L | Same as CORE | USER | C_LOCALE.
CORE_SYSTEM | Deprecated, same as CORE | SYSTEM. Use CORE_SYSTEM_L instead.
CORE_USER | Deprecated, same as CORE | USER. Use CORE_USER_L instead.

## Constructor & Destructor Documentation

## ◆ Fl_Preferences() [1/8]

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

The constructor creates a group that manages key/value pairs and child groups.

Preferences can be stored per user using the root type Fl_Preferences::USER_L, or stored system-wide using Fl_Preferences::SYSTEM_L.

Groups and key/value pairs can be read and written randomly. Reading undefined values will return the default value. Writing undefined values will create all required groups and key/vlaue pairs.

This constructor creates the base instance for all following entries and reads the database from disk into memory if it exists. The vendor argument is a unique text string identifying the development team or vendor of an application. A domain name or an EMail address (replacing the '@' with a '.') are great unique names, e.g. "research.matthiasm.com" or "fluid.fltk.org". The application argument can be the working title or final name of your application. Both vendor and application must be valid UNIX path segments as they become parts of the preference file path and may contain forward slashes to create deeper file structures.

Note
  On Windows, the directory is constructed by querying the Common AppData or AppData key of the Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders registry entry. The filename and path is then constructed as $(query)/$(vendor)/$(application).prefs . If the query call fails, data will be stored in RAM only. It will be lost when the app exits.

In FLTK versions before 1.4.0, if querying the registry failed,
  preferences would be written to C:\FLTK\$(vendor)\$(application).prefs .

Note
  On Linux, the `USER` directory is constructed by reading `$HOME` . If `$HOME` is not set or not pointing to an existing directory, FLTK will check the path member of the passwd struct returned by `getpwuid(getuid())` . If all attempts fail, data will be stored in RAM only and be lost when the app exits.

The `SYSTEM` preference filename is hardcoded as /etc/fltk/$(vendor)/$(application).prefs .

For backward compatibility, the old `USER` .prefs file naming scheme $(directory)/.fltk/$(vendor)/$(application).prefs is checked first. If that file does not exist, the environment variable $XDG_CONFIG_HOME is read as a base directory. If $XDG_CONFIG_HOME is not set, the base directory defaults to $HOME/.config/.

The user preferences will be stored in $(directory)/$(vendor)/$(application).prefs. The user data path will be $(directory)/$(vendor)/$(application)/.

In FLTK versions before 1.4.0, if `$HOME` was not set, the `USER` path would be empty, generating $(vendor)/$(application).prefs, which was used relative to the current working directory.

Note
  On macOS, the `USER` directory is constructed by reading `$HOME` . If `$HOME` is not set or not pointing to an existing directory, we check the path returned by `NSHomeDirectory()` , and finally checking the path member of the passwd struct returned by `getpwuid(getuid())` . If all attempts fail, data will be stored in RAM only and be lost when the app exits. The filename and path is then constructed as $(directory)/Library/Preferences/$(vendor)/$(application).prefs . The `SYSTEM` directory is hardcoded as /Library/Preferences/$(vendor)/$(application).prefs .

In FLTK versions before 1.4.0, if `$HOME` was not set, the `USER` path
  would be `NULL` , generating <null>/Library/Preferences/$(vendor)/$(application).prefs, which would silently fail to create a preference file.

Parameters

  [in] | root | can be `USER_L` or `SYSTEM_L` for user specific or system wide preferences, add the `CLEAR` flag to start with a clean set of preferences instead of reading them from a preexisting database
  [in] | vendor | unique text describing the company or author of this file, must be a valid filepath segment
  [in] | application | unique text describing the application, must be a valid filepath segment

See also
  Fl_Preferences(Fl_Preferences *parent, const char *group) with parent set to NULL

## ◆ Fl_Preferences() [2/8]

Fl_Preferences::Fl_Preferences | ( | const char * | path,
|  | const char * | vendor,
|  | const char * | application,
|  | Root | flags )

Use this constructor to create or read a preference 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` is taken literally as the file path and name.

// Example: read from an existing database and write modifications when flushed
// or destructor is called
Fl_Preferences database("/user/matt/test.prefs", "org.fltk.test", NULL,
Fl_Preferences::C_LOCALE);
// Example: create a new preferences file with an empty data set
Fl_Preferences database("/user/matt/test.prefs", "org.fltk.test", NULL,
(Fl_Preferences::Root)(Fl_Preferences::C_LOCALE|Fl_Preferences::CLEAR));
Fl_Preferences::Root
Root
Define the scope of the preferences.
Definition Fl_Preferences.H:131
Fl_Preferences::C_LOCALE
@ C_LOCALE
This flag should always be set to ensure that floating point values are written and read correctly in...
Definition Fl_Preferences.H:138
Fl_Preferences::CLEAR
@ CLEAR
Don't read a possibly existing database. Instead, start with an empty set of preferences.
Definition Fl_Preferences.H:140

Note
  the C_LOCALE flag is is not set by default for backward compatibility, but it is highly recommended to set it when opening a database.

Parameters

  [in] | path | path to the directory that contains the preference file
  [in] | vendor | unique text describing the company or author of this file, must be a valid file path segment
  [in] | application | unique text describing the application, must be a valid filename or NULL
  [in] | flags | C_LOCALE to make the preferences file independent of the current locale, add the CLEAR flag to start with a clean set of preferences instead of reading from the database

## ◆ Fl_Preferences() [3/8]

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)

## ◆ Fl_Preferences() [4/8]

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

Create or access a group of preferences using a name.

Parent should point to a previously created parent preferences group to create a preferences hierarchy.

If parent is set to NULL, an unnamed database will be accessed that exists only in local memory and is not associated with a file on disk. The root type of this database is set to Fl_Preferences::MEMORY.

- the memory database is not shared among multiple instances of the same app
- memory databases are not thread safe
- all data will be lost when the app quits

void some_function() {
Fl_Preferences guide( NULL, "Guide" );
guide.set("answer", 42);
}
void other_function() {
int x;
Fl_Preferences guide( NULL, "Guide" );
guide.get("answer", x, -1);
}

FLTK uses the memory database to manage plugins. See Fl_Plugin.

Parameters

  [in] | parent | the parameter parent is a pointer to the parent group. If `parent` is `NULL`, the new preferences item refers to an application internal database ("runtime prefs") 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. Runtime prefs are not thread-safe.
  [in] | group | a group name that is used as a key into the database

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

## ◆ Fl_Preferences() [5/8]

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

## ◆ Fl_Preferences() [6/8]

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

See also
  Fl_Preferences( Fl_Preferences&, int groupIndex )

## ◆ Fl_Preferences() [7/8]

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 very helpful when put into the user_data() field of widget callbacks.

## ◆ ~Fl_Preferences()

Fl_Preferences::~Fl_Preferences | ( |  | ) |
| virtual

The destructor removes allocated resources.

When used on the base preferences group, the destructor flushes all changes to the preference file and deletes all internal databases.

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

## ◆ Fl_Preferences() [8/8]

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

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

Deprecated
  "since 1.4.0 - use Fl_Preferences(path, vendor, application, flags) instead"

This constructor should no longer be used because the generated database uses the current locale, making it impossible to exchange floating point settings between machines with different language settings.

Use Fl_Preferences(path, vendor, application, Fl_Preferences::C_LOCALE) in new projects and Fl_Preferences(path, vendor, application, 0) if you must keep backward compatibility.

See also
  Fl_Preferences( const char *path, const char *vendor, const char *application, Root flags )

## Member Function Documentation

## ◆ delete_entry()

char Fl_Preferences::delete_entry | ( | 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

## ◆ delete_group()

char Fl_Preferences::delete_group | ( | 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

## ◆ dirty()

int Fl_Preferences::dirty | ( |  | ) |

Check if there were changes to the database that need to be written to disk.

Returns
  1 if the database will be written to disk by flush or destructor.
  0 if the database is unchanged since the last write operation.
  -1 f there is an internal database error.

## ◆ entries()

int Fl_Preferences::entries | ( |  | ) |

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

Returns
  number of entries

## ◆ entry()

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

## ◆ entry_exists()

char Fl_Preferences::entry_exists | ( | 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

## ◆ file_access() [1/2]

unsigned int Fl_Preferences::file_access | ( |  | ) |
| static

Return the current file access permissions for the FLTK preferences system.

See also
  Fl_Preferences::file_access(unsigned int)

## ◆ file_access() [2/2]

void Fl_Preferences::file_access | ( | unsigned int | flags | ) |
| static

Tell the FLTK preferences system which files in the file system it may read, create, or write.

The FLTK core library will try to read or even create or write preference files when calling Fl::option(), Fl_File_Chooser, the printing panel, and possibly some other internal functions. If your application wants to keep FLTK from touching the file system, call this function before making any other FLTK calls:

// neither FLTK nor the app may read, create, or write preference files
Fl_Preferences::file_access( Fl_Preferences::NONE );
Fl_Preferences::NONE
static const unsigned int NONE
Set this if no call to Fl_Preferences shall access the file system.
Definition Fl_Preferences.H:164
Fl_Preferences::file_access
static unsigned int file_access()
Return the current file access permissions for the FLTK preferences system.
Definition Fl_Preferences.cxx:238

or

// FLTK may not read, create, or write preference files, but the application may
Fl_Preferences::file_access( Fl_Preferences::APP_OK );
Fl_Preferences::APP_OK
static const unsigned int APP_OK
Set this if it is OK for applications to read, create, and write any kind of preference files.
Definition Fl_Preferences.H:178

All flags can be combined using an OR operator. If flags are not set, that specific access to the file system will not be allowed. By default, all access is granted. To clear one or more flags from the default setting, use:

Fl_Preferences::file_access( Fl_Preferences::file_access()
&~ Fl_Preferences::SYSTEM_WRITE );
Fl_Preferences::file_access
static void file_access(unsigned int flags)
Tell the FLTK preferences system which files in the file system it may read, create,...
Definition Fl_Preferences.cxx:228

If preferences are created using a filename (instead of Fl_Preferences::USER or Fl_Preferences::SYSTEM), file access is handled as if the Fl_Preferences::USER flag was set.

See also
  Fl_Preferences::NONE and others for a list of flags.
  Fl_Preferences::file_access()

## ◆ filename() [1/2]

Fl_Preferences::Root Fl_Preferences::filename | ( | char * | buffer,
|  | size_t | buffer_size )

Return the file name and path to the preference file.

If the preferences have not changed or have not been flushed, the file or directory may not have been created yet.

Parameters

  [out] | buffer | write the resulting path into this buffer
  [in] | buffer_size | size of the buffer in bytes

Returns
  the root type at creation type, or MEMORY for runtime prefs, it does not return CORE or LOCALE flags.

## ◆ filename() [2/2]

Fl_Preferences::Root Fl_Preferences::filename | ( | char * | buffer,
|  | size_t | buffer_size,
|  | Root | root,
|  | const char * | vendor,
|  | const char * | application )
| static

Determine the file name and path to preferences that would be opened with these parameters.

Find the possible location of a preference file on disk without touching any of the pathname components. This can be used to check if a preference file already exists.

Parameters

  [out] | buffer | write the resulting path into this buffer
  [in] | buffer_size | size of the buffer in bytes
  [in] | root | can be `USER_L` or `SYSTEM_L` for user specific or system wide preferences
  [in] | vendor | unique text describing the company or author of this file, must be a valid filepath segment
  [in] | application | unique text describing the application, must be a valid filepath segment

Returns
  the input root value, or Fl_Preferences::UNKNOWN_ROOT_TYPE if the path could not be determined.

See also
  Fl_Preferences( Root root, const char *vendor, const char *application )

## ◆ flush()

int Fl_Preferences::flush | ( |  | ) |

Writes preferences to disk if they were modified.

This method can be used to verify that writing a preference file went well. Deleting the base preferences object will also write the contents of the database to disk.

Returns
  -1 if anything went wrong, i.e. file could not be opened, permissions blocked writing, etc.
  0 if the file was written to disk. This does not check if the disk ran out of space and the file is truncated.
  1 if no data was written to the database and no write attempt to disk was made.

## ◆ get() [1/8]

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

## ◆ get() [2/8]

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 trailing 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

## ◆ get() [3/8]

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

## ◆ get() [4/8]

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

## ◆ get() [5/8]

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

## ◆ get() [6/8]

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

## ◆ get() [7/8]

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

Reads a binary entry from the group, encoded in hexadecimal blocks.

A binary (not hex) default value can 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 and returns the actual number of bytes 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,out] | maxSize | maximum length of value and actual number of bytes set

Returns
  0 if the default value was used

## ◆ get() [8/8]

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

Reads a binary entry from the group, encoded in hexadecimal blocks.

Parameters

  [in] | key | name of entry
  [out] | data | value returned from preferences or default value if none was set
  [in] | defaultValue | default value
  [in] | defaultSize | size of default value array
  [in] | maxSize | maximum length of value, to receive the number of bytes read, use the function below instead.

Returns
  0 if the default value was used

See also
  Fl_Preferences::get( const char *key, void *data, const void *defaultValue, int defaultSize, int *maxSize )

## ◆ get_userdata_path()

char Fl_Preferences::get_userdata_path | ( | char * | path,
|  | int | pathlen )

Creates a path that is related to the preference 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.

There is no way to verify that the path name fit into the buffer. If the name is too long, it will be clipped.

This function can be used with direct paths that don't end in ``.prefs . getUserDataPath() will remove any extension and end the path with a `/` . If the file name has no extension, getUserDataPath() will append ``.data/ to the path name.

Example:

Fl_Preferences prefs( USER, "matthiasm.com", "test" );
char path[FL_PATH_MAX];
prefs.getUserdataPath( path, FL_PATH_MAX );
Fl_Preferences::USER
@ USER
Preferences apply only to the current user. Deprecated, see USER_L.
Definition Fl_Preferences.H:134
Fl_Preferences::path
const char * path()
Return the full path to this entry.
Definition Fl_Preferences.H:225
FL_PATH_MAX
#define FL_PATH_MAX
all path buffers should use this length
Definition filename.H:45

creates the preferences database in the directory (User 'matt' on Linux):

/Users/matt/.fltk/matthiasm.com/test.prefs

..and returns the userdata path:

/Users/matt/.fltk/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
  1 if there is no filename (path will be unmodified)
  1 if pathlen is 0 (path will be unmodified)
  1 if a path was created successfully, path will contain the path name ending in a '/'
  0 if path was not created for some reason; path will contain the pathname that could not be created

See also
  Fl_Preferences::Fl_Preferences(Root, const char*, const char*)

## ◆ group()

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

## ◆ group_exists()

char Fl_Preferences::group_exists | ( | const char * | key | ) |

Returns non-zero if a group with this name exists.

Group names are relative to the Fl_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

## ◆ groups()

int Fl_Preferences::groups | ( |  | ) |

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

Returns
  0 for no groups at all

## ◆ new_UUID()

const char * Fl_Preferences::new_UUID | ( |  | ) |
| 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!

## ◆ set() [1/7]

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 preference file.

Parameters

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

Returns
  0 if setting the value failed

## ◆ set() [2/7]

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 preference 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

## ◆ set() [3/7]

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 preference file.

Parameters

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

Returns
  0 if setting the value failed

## ◆ set() [4/7]

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 preference 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

## ◆ set() [5/7]

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 preference file.

Parameters

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

Returns
  0 if setting the value failed

## ◆ set() [6/7]

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 preference 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

## ◆ set() [7/7]

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 preference file.

Parameters

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

Returns
  0 if setting the value failed

## ◆ size()

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

## Member Data Documentation

## ◆ CORE_READ_OK

const unsigned int Fl_Preferences::CORE_READ_OK = 0x0010
| static

Set this if it is OK for FLTK to read preference files.

USER_READ_OK and/or SYSTEM_READ_OK must also be set.

## ◆ CORE_WRITE_OK

const unsigned int Fl_Preferences::CORE_WRITE_OK = 0x0020
| static

Set this if it is OK for FLTK to create or write preference files.

USER_WRITE_OK and/or SYSTEM_WRITE_OK must also be set.

## ◆ NONE

const unsigned int Fl_Preferences::NONE = 0x0000
| static

Set this if no call to Fl_Preferences shall access the file system.

See also
  Fl_Preferences::file_access(unsigned int)
  Fl_Preferences::file_access()

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

- Fl_Preferences.H
- Fl_Preferences.cxx