doc-1.5/Fl__Preferences_8H_source.html

//

// Preferences implementation for the Fast Light Tool Kit (FLTK).

//

// Copyright 2002-2023 by Matthias Melcher.

//

// This library is free software. Distribution and use rights are outlined in

// the file "COPYING" which should have been included with this file.  If this

// file is missing or damaged, see the license at:

//

//     https://www.fltk.org/COPYING.php

//

// Please see the following page on how to report bugs and issues:

//

//     https://www.fltk.org/bugs.php

//


/* \file

   Fl_Preferences class . */


#ifndef Fl_Preferences_H

#  define Fl_Preferences_H


#  include <stdio.h>

#  include "Fl_Export.H"

#  include "fl_attr.h"


#include <string>


class FL_EXPORT Fl_Preferences {


public:


  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

  };


  typedef void *ID;


  static const char *new_UUID();


  static const unsigned int NONE = 0x0000;

  static const unsigned int USER_READ_OK = 0x0001;

  static const unsigned int USER_WRITE_OK = 0x0002;

  static const unsigned int USER_OK = USER_READ_OK | USER_WRITE_OK;

  static const unsigned int SYSTEM_READ_OK = 0x0004;

  static const unsigned int SYSTEM_WRITE_OK = 0x0008;

  static const unsigned int SYSTEM_OK = SYSTEM_READ_OK | SYSTEM_WRITE_OK;

  static const unsigned int APP_OK = SYSTEM_OK | USER_OK;

  static const unsigned int CORE_READ_OK = 0x0010;

  static const unsigned int CORE_WRITE_OK = 0x0020;

  static const unsigned int CORE_OK = CORE_READ_OK | CORE_WRITE_OK;

  static const unsigned int ALL_READ_OK = USER_READ_OK | SYSTEM_READ_OK | CORE_READ_OK;

  static const unsigned int ALL_WRITE_OK = USER_WRITE_OK | SYSTEM_WRITE_OK | CORE_WRITE_OK;

  static const unsigned int ALL = ALL_READ_OK | ALL_WRITE_OK;


  static void file_access(unsigned int flags);

  static unsigned int file_access();

  static Root filename( char *buffer, size_t buffer_size, Root root, const char *vendor, const char *application );


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

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

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

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

  Fl_Preferences( Fl_Preferences &parent, int groupIndex );

  Fl_Preferences( Fl_Preferences *parent, int groupIndex );

  Fl_Preferences(const Fl_Preferences&);

  Fl_Preferences( ID id );

  virtual ~Fl_Preferences();


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

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


  Root filename( char *buffer, size_t buffer_size);


  ID id() { return (ID)node; }


  static char remove(ID id_) { return ((Node*)id_)->remove(); }


  const char *name() { return node->name(); }


  const char *path() { return node->path(); }


  int groups();

  const char *group( int num_group );

  char group_exists( const char *key );

  char delete_group( const char *group );

  char delete_all_groups();


  int entries();

  const char *entry( int index );

  char entry_exists( const char *key );

  char delete_entry( const char *entry );

  char delete_all_entries();


  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 set( const char *entry, const std::string &value );


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

  char get( const char *entry, void *value,   const void *defaultValue, int defaultSize, int *size );

  char get( const char *entry, std::string &value, const std::string &defaultValue );


  int size( const char *entry );


  char get_userdata_path( char *path, int pathlen );


  int flush();


  int dirty();


  static const char *newUUID() { return new_UUID(); }

  char groupExists( const char *key ) { return group_exists(key); }

  char deleteGroup( const char *group ) { return delete_group(group); }

  char deleteAllGroups() { return delete_all_groups(); }

  char entryExists( const char *key ) { return entry_exists(key); }

  char deleteEntry( const char *entry ) { return delete_entry(entry); }

  char deleteAllEntries() { return delete_all_entries(); }

  char getUserdataPath( char *path, int pathlen ) { return get_userdata_path(path, pathlen); }


  class FL_EXPORT Name {


    char *data_;


  public:

    Name( unsigned int n );

    Name( const char *format, ... );


    operator const char *() { return data_; }

    ~Name();

  };


  struct Entry {

    char *name, *value;

  };


private:

  Fl_Preferences() : node(0), rootNode(0) { }

  Fl_Preferences &operator=(const Fl_Preferences&);


  static char nameBuffer[128];

  static char uuidBuffer[40];

  static Fl_Preferences *runtimePrefs;

  static unsigned int fileAccess_;


public:  // older Sun compilers need this (public definition of the following classes)

  class RootNode;


  class FL_EXPORT Node {        // a node contains a list to all its entries

                                // and all means to manage the tree structure

    Node *first_child_, *next_;

    union {                     // these two are mutually exclusive

      Node *parent_;            // top_ bit clear

      RootNode *root_node_;     // top_ bit set

    };

    char *path_;

    Entry *entry_;

    int nEntry_, NEntry_;

    unsigned char dirty_:1;

    unsigned char top_:1;

    unsigned char indexed_:1;

    // indexing routines

    Node **index_;

    int nIndex_, NIndex_;

    void createIndex();

    void updateIndex();

    void deleteIndex();

  public:

    static int lastEntrySet;

  public:

    Node( const char *path );

    ~Node();

    // node methods

    int write( FILE *f );

    const char *name();

    const char *path() { return path_; }

    Node *find( const char *path );

    Node *search( const char *path, int offset=0 );

    Node *childNode( int ix );

    Node *addChild( const char *path );

    void setParent( Node *parent );

    Node *parent() { return top_?0L:parent_; }

    void setRoot(RootNode *r) { root_node_ = r; top_ = 1; }

    RootNode *findRoot();

    char remove();

    char dirty();

    void clearDirtyFlags();

    void deleteAllChildren();

    // entry methods

    int nChildren();

    const char *child( int ix );

    void set( const char *name, const char *value );

    void set( const char *line );

    void add( const char *line );

    const char *get( const char *name );

    int getEntry( const char *name );

    char deleteEntry( const char *name );

    void deleteAllEntries();

    int nEntry() { return nEntry_; }

    Entry &entry(int i) { return entry_[i]; }

  };


  friend class Node;


  class FL_EXPORT RootNode {    // the root node manages file paths and basic reading and writing

    Fl_Preferences *prefs_;

    char *filename_;

    char *vendor_, *application_;

    Root root_type_;

  public:

    RootNode( Fl_Preferences *, Root root, const char *vendor, const char *application );

    RootNode( Fl_Preferences *, const char *path, const char *vendor, const char *application, Root flags );

    RootNode( Fl_Preferences * );

    ~RootNode();

    int read();

    int write();

    char getPath( char *path, int pathlen );

    char *filename() { return filename_; }

    Root root() { return root_type_; }

  };


  friend class RootNode;


protected:

  Node *node;

  RootNode *rootNode;

};


#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:288

Fl_Preferences::Node
Definition Fl_Preferences.H:321

Fl_Preferences::RootNode
Definition Fl_Preferences.H:376

Fl_Preferences
Fl_Preferences store user settings between application starts.
Definition Fl_Preferences.H:122

Fl_Preferences::Root
Root
Define the scope of the preferences.
Definition Fl_Preferences.H:128

Fl_Preferences::USER
@ USER
Preferences apply only to the current user. Deprecated, see USER_L.
Definition Fl_Preferences.H:131

Fl_Preferences::MEMORY
@ MEMORY
Returned if querying memory mapped preferences.
Definition Fl_Preferences.H:132

Fl_Preferences::id
ID id()
Return an ID that can later be reused to open more references to this dataset.
Definition Fl_Preferences.H:210

Fl_Preferences::path
const char * path()
Return the full path to this entry.
Definition Fl_Preferences.H:222

Fl_Preferences::name
const char * name()
Return the name of this entry.
Definition Fl_Preferences.H:218

Fl_Preferences::remove
static char remove(ID id_)
Remove the group with this ID from a database.
Definition Fl_Preferences.H:214

Fl_Preferences::ID
void * ID
Every Fl_Preferences-Group has a unique ID.
Definition Fl_Preferences.H:153

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:67

Fl_Preferences::Entry
Definition Fl_Preferences.H:305