FLTK 1.4.4

Loading...
Searching...
No Matches
Fl_Preferences.H
1//
2// Preferences implementation for the Fast Light Tool Kit (FLTK).
3//
4// Copyright 2002-2023 by Matthias Melcher.
5//
6// This library is free software. Distribution and use rights are outlined in
7// the file "COPYING" which should have been included with this file. If this
8// file is missing or damaged, see the license at:
9//
10// https://www.fltk.org/COPYING.php
11//
12// Please see the following page on how to report bugs and issues:
13//
14// https://www.fltk.org/bugs.php
15//
16
17/* \file
18 Fl_Preferences class . */
19
20#ifndef Fl_Preferences_H
21# define Fl_Preferences_H
22
23# include <stdio.h>
24# include "Fl_Export.H"
25# include "fl_attr.h"
26
27//class Fl_String;
28#if (FLTK_USE_STD)
29#include <string>
30#endif
31
125 class FL_EXPORT Fl_Preferences {
126
127 public:
131 enum Root {
132 UNKNOWN_ROOT_TYPE = -1,
133 SYSTEM = 0,
134 USER,
135 MEMORY,
136 ROOT_MASK = 0x00FF,
137 CORE = 0x0100,
138 C_LOCALE = 0x1000,
140 CLEAR = 0x2000,
141 SYSTEM_L = SYSTEM | C_LOCALE,
142 USER_L = USER | C_LOCALE,
143 CORE_SYSTEM_L = CORE | SYSTEM_L,
144 CORE_USER_L = CORE | USER_L,
145 CORE_SYSTEM = CORE | SYSTEM,
146 CORE_USER = CORE | USER
147 };
148
156 typedef void *ID;
157
158 static const char *new_UUID();
159
164 static const unsigned int NONE = 0x0000;
166 static const unsigned int USER_READ_OK = 0x0001;
168 static const unsigned int USER_WRITE_OK = 0x0002;
170 static const unsigned int USER_OK = USER_READ_OK | USER_WRITE_OK;
172 static const unsigned int SYSTEM_READ_OK = 0x0004;
174 static const unsigned int SYSTEM_WRITE_OK = 0x0008;
176 static const unsigned int SYSTEM_OK = SYSTEM_READ_OK | SYSTEM_WRITE_OK;
178 static const unsigned int APP_OK = SYSTEM_OK | USER_OK;
180 static const unsigned int CORE_READ_OK = 0x0010;
182 static const unsigned int CORE_WRITE_OK = 0x0020;
184 static const unsigned int CORE_OK = CORE_READ_OK | CORE_WRITE_OK;
186 static const unsigned int ALL_READ_OK = USER_READ_OK | SYSTEM_READ_OK | CORE_READ_OK;
188 static const unsigned int ALL_WRITE_OK = USER_WRITE_OK | SYSTEM_WRITE_OK | CORE_WRITE_OK;
190 static const unsigned int ALL = ALL_READ_OK | ALL_WRITE_OK;
191
192 static void file_access(unsigned int flags);
193 static unsigned int file_access();
194 static Root filename( char *buffer, size_t buffer_size, Root root, const char *vendor, const char *application );
195
196 Fl_Preferences( Root root, const char *vendor, const char *application );
197 Fl_Preferences( const char *path, const char *vendor, const char *application, Root flags );
198 Fl_Preferences( Fl_Preferences &parent, const char *group );
199 Fl_Preferences( Fl_Preferences *parent, const char *group );
200 Fl_Preferences( Fl_Preferences &parent, int groupIndex );
201 Fl_Preferences( Fl_Preferences *parent, int groupIndex );
202 Fl_Preferences(const Fl_Preferences&);
203 Fl_Preferences( ID id );
204 virtual ~Fl_Preferences();
205
206 FL_DEPRECATED("since 1.4.0 - use Fl_Preferences(path, vendor, application, flags) instead",
207 Fl_Preferences( const char *path, const char *vendor, const char *application ) );
208
209 Root filename( char *buffer, size_t buffer_size);
210
213 ID id() { return (ID)node; }
214
217 static char remove(ID id_) { return ((Node*)id_)->remove(); }
218
221 const char *name() { return node->name(); }
222
225 const char *path() { return node->path(); }
226
227 int groups();
228 const char *group( int num_group );
229 char group_exists( const char *key );
230 char delete_group( const char *group );
231 char delete_all_groups();
232
233 int entries();
234 const char *entry( int index );
235 char entry_exists( const char *key );
236 char delete_entry( const char *entry );
237 char delete_all_entries();
238
239 char clear();
240
241 char set( const char *entry, int value );
242 char set( const char *entry, float value );
243 char set( const char *entry, float value, int precision );
244 char set( const char *entry, double value );
245 char set( const char *entry, double value, int precision );
246 char set( const char *entry, const char *value );
247 char set( const char *entry, const void *value, int size );
248
249 char get( const char *entry, int &value, int defaultValue );
250 char get( const char *entry, float &value, float defaultValue );
251 char get( const char *entry, double &value, double defaultValue );
252 char get( const char *entry, char *&value, const char *defaultValue );
253 char get( const char *entry, char *value, const char *defaultValue, int maxSize );
254 char get( const char *entry, void *&value, const void *defaultValue, int defaultSize );
255 char get( const char *entry, void *value, const void *defaultValue, int defaultSize, int maxSize );
256 char get( const char *entry, void *value, const void *defaultValue, int defaultSize, int *size );
257
258// char set( const char *entry, const Fl_String &value );
259// char get( const char *entry, Fl_String &value, const Fl_String &defaultValue );
260
261#if (FLTK_USE_STD)
262 char set( const char *entry, const std::string &value );
263 char get( const char *entry, std::string &value, const std::string &defaultValue );
264#endif
265
266 int size( const char *entry );
267
268 char get_userdata_path( char *path, int pathlen );
269
270 int flush();
271
272 int dirty();
273
275 static const char *newUUID() { return new_UUID(); }
276 char groupExists( const char *key ) { return group_exists(key); }
277 char deleteGroup( const char *group ) { return delete_group(group); }
278 char deleteAllGroups() { return delete_all_groups(); }
279 char entryExists( const char *key ) { return entry_exists(key); }
280 char deleteEntry( const char *entry ) { return delete_entry(entry); }
281 char deleteAllEntries() { return delete_all_entries(); }
282 char getUserdataPath( char *path, int pathlen ) { return get_userdata_path(path, pathlen); }
284
297 class FL_EXPORT Name {
298
299 char *data_;
300
301 public:
302 Name( unsigned int n );
303 Name( const char *format, ... );
304
309 operator const char *() { return data_; }
310 ~Name();
311 };
312
314 struct Entry {
315 char *name, *value;
316 };
317
318 private:
319 Fl_Preferences() : node(0), rootNode(0) { }
320 Fl_Preferences &operator=(const Fl_Preferences&);
321
322 static char nameBuffer[128];
323 static char uuidBuffer[40];
324 static Fl_Preferences *runtimePrefs;
325 static unsigned int fileAccess_;
326
327 public: // older Sun compilers need this (public definition of the following classes)
328 class RootNode;
329
330 class FL_EXPORT Node { // a node contains a list to all its entries
331 // and all means to manage the tree structure
332 Node *first_child_, *next_;
333 union { // these two are mutually exclusive
334 Node *parent_; // top_ bit clear
335 RootNode *root_node_; // top_ bit set
336 };
337 char *path_;
338 Entry *entry_;
339 int nEntry_, NEntry_;
340 unsigned char dirty_:1;
341 unsigned char top_:1;
342 unsigned char indexed_:1;
343 // indexing routines
344 Node **index_;
345 int nIndex_, NIndex_;
346 void createIndex();
347 void updateIndex();
348 void deleteIndex();
349 public:
350 static int lastEntrySet;
351 public:
352 Node( const char *path );
353 ~Node();
354 // node methods
355 int write( FILE *f );
356 const char *name();
357 const char *path() { return path_; }
358 Node *find( const char *path );
359 Node *search( const char *path, int offset=0 );
360 Node *childNode( int ix );
361 Node *addChild( const char *path );
362 void setParent( Node *parent );
363 Node *parent() { return top_?0L:parent_; }
364 void setRoot(RootNode *r) { root_node_ = r; top_ = 1; }
365 RootNode *findRoot();
366 char remove();
367 char dirty();
368 void clearDirtyFlags();
369 void deleteAllChildren();
370 // entry methods
371 int nChildren();
372 const char *child( int ix );
373 void set( const char *name, const char *value );
374 void set( const char *line );
375 void add( const char *line );
376 const char *get( const char *name );
377 int getEntry( const char *name );
378 char deleteEntry( const char *name );
379 void deleteAllEntries();
380 int nEntry() { return nEntry_; }
381 Entry &entry(int i) { return entry_[i]; }
382 };
383 friend class Node;
384
385 class FL_EXPORT RootNode { // the root node manages file paths and basic reading and writing
386 Fl_Preferences *prefs_;
387 char *filename_;
388 char *vendor_, *application_;
389 Root root_type_;
390 public:
391 RootNode( Fl_Preferences *, Root root, const char *vendor, const char *application );
392 RootNode( Fl_Preferences *, const char *path, const char *vendor, const char *application, Root flags );
393 RootNode( Fl_Preferences * );
394 ~RootNode();
395 int read();
396 int write();
397 char getPath( char *path, int pathlen );
398 char *filename() { return filename_; }
399 Root root() { return root_type_; }
400 };
401 friend class RootNode;
402
403 protected:
404 Node *node;
405 RootNode *rootNode;
406};
407
408#endif // !Fl_Preferences_H
Fl_Preferences::Name
'Name' provides a simple method to create numerical or more complex procedural names for entries and ...
Definition Fl_Preferences.H:297
Fl_Preferences::Name::Name
Name(unsigned int n)
Creates a group name or entry name on the fly.
Definition Fl_Preferences.cxx:1298
Fl_Preferences::Node
Definition Fl_Preferences.H:330
Fl_Preferences::RootNode
Definition Fl_Preferences.H:385
Fl_Preferences
Fl_Preferences store user settings between application starts.
Definition Fl_Preferences.H:125
Fl_Preferences::Root
Root
Define the scope of the preferences.
Definition Fl_Preferences.H:131
Fl_Preferences::SYSTEM
@ SYSTEM
Preferences are used system-wide. Deprecated, see SYSTEM_L.
Definition Fl_Preferences.H:133
Fl_Preferences::UNKNOWN_ROOT_TYPE
@ UNKNOWN_ROOT_TYPE
Returned if storage could not be determined.
Definition Fl_Preferences.H:132
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::USER_L
@ USER_L
Preferences apply only to the current user, locale independent.
Definition Fl_Preferences.H:142
Fl_Preferences::CORE_USER
@ CORE_USER
Deprecated, same as CORE | USER. Use CORE_USER_L instead.
Definition Fl_Preferences.H:146
Fl_Preferences::CORE_SYSTEM_L
@ CORE_SYSTEM_L
Same as CORE | SYSTEM | C_LOCALE.
Definition Fl_Preferences.H:143
Fl_Preferences::ROOT_MASK
@ ROOT_MASK
Mask for the values above.
Definition Fl_Preferences.H:136
Fl_Preferences::CLEAR
@ CLEAR
Don't read a possibly existing database. Instead, start with an empty set of preferences.
Definition Fl_Preferences.H:140
Fl_Preferences::CORE_USER_L
@ CORE_USER_L
Same as CORE | USER | C_LOCALE.
Definition Fl_Preferences.H:144
Fl_Preferences::CORE
@ CORE
OR'd by FLTK to read and write core library preferences and options.
Definition Fl_Preferences.H:137
Fl_Preferences::SYSTEM_L
@ SYSTEM_L
Preferences are used system-wide, locale independent.
Definition Fl_Preferences.H:141
Fl_Preferences::USER
@ USER
Preferences apply only to the current user. Deprecated, see USER_L.
Definition Fl_Preferences.H:134
Fl_Preferences::MEMORY
@ MEMORY
Returned if querying memory mapped preferences.
Definition Fl_Preferences.H:135
Fl_Preferences::CORE_SYSTEM
@ CORE_SYSTEM
Deprecated, same as CORE | SYSTEM. Use CORE_SYSTEM_L instead.
Definition Fl_Preferences.H:145
Fl_Preferences::ALL_WRITE_OK
static const unsigned int ALL_WRITE_OK
Set this to allow FLTK and applications to create and write preference files.
Definition Fl_Preferences.H:188
Fl_Preferences::id
ID id()
Return an ID that can later be reused to open more references to this dataset.
Definition Fl_Preferences.H:213
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::CORE_READ_OK
static const unsigned int CORE_READ_OK
Set this if it is OK for FLTK to read preference files.
Definition Fl_Preferences.H:180
Fl_Preferences::filename
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.
Definition Fl_Preferences.cxx:263
Fl_Preferences::SYSTEM_OK
static const unsigned int SYSTEM_OK
Set this if it is OK for applications to read, create, and write system wide preference files.
Definition Fl_Preferences.H:176
Fl_Preferences::USER_READ_OK
static const unsigned int USER_READ_OK
Set this if it is OK for applications to read user preference files.
Definition Fl_Preferences.H:166
Fl_Preferences::path
const char * path()
Return the full path to this entry.
Definition Fl_Preferences.H:225
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
Fl_Preferences::new_UUID
static const char * new_UUID()
Returns a UUID as generated by the system.
Definition Fl_Preferences.cxx:188
Fl_Preferences::ID
void * ID
Every Fl_Preferences-Group has a unique ID.
Definition Fl_Preferences.H:156
Fl_Preferences::name
const char * name()
Return the name of this entry.
Definition Fl_Preferences.H:221
Fl_Preferences::remove
static char remove(ID id_)
Remove the group with this ID from a database.
Definition Fl_Preferences.H:217
Fl_Preferences::SYSTEM_READ_OK
static const unsigned int SYSTEM_READ_OK
Set this if it is OK for applications to read system wide preference files.
Definition Fl_Preferences.H:172
Fl_Preferences::group
const char * group(int num_group)
Returns the name of the Nth (num_group) group.
Definition Fl_Preferences.cxx:630
Fl_Preferences::SYSTEM_WRITE_OK
static const unsigned int SYSTEM_WRITE_OK
Set this if it is OK for applications to create and write system wide preference files.
Definition Fl_Preferences.H:174
Fl_Preferences::ALL
static const unsigned int ALL
Set this to give FLTK and applications permission to read, write, and create preference files.
Definition Fl_Preferences.H:190
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
Fl_Preferences::ALL_READ_OK
static const unsigned int ALL_READ_OK
Set this to allow FLTK and applications to read preference files.
Definition Fl_Preferences.H:186
Fl_Preferences::USER_WRITE_OK
static const unsigned int USER_WRITE_OK
Set this if it is OK for applications to create and write user preference files.
Definition Fl_Preferences.H:168
Fl_Preferences::CORE_OK
static const unsigned int CORE_OK
Set this if it is OK for FLTK to read, create, or write preference files.
Definition Fl_Preferences.H:184
Fl_Preferences::USER_OK
static const unsigned int USER_OK
Set this if it is OK for applications to read, create, and write user preference files.
Definition Fl_Preferences.H:170
Fl_Preferences::CORE_WRITE_OK
static const unsigned int CORE_WRITE_OK
Set this if it is OK for FLTK to create or write preference files.
Definition Fl_Preferences.H:182
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
fl_attr.h
This file defines compiler-specific macros.
FL_DEPRECATED
#define FL_DEPRECATED(msg, func)
Enclosing a function or method in FL_DEPRECATED marks it as no longer recommended.
Definition fl_attr.h:57
Fl_Preferences::Entry
Definition Fl_Preferences.H:314