Humble Framework for SkyOS
Main Page | Modules | Class Hierarchy | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

HSettings Class Reference
[System]

#include <HSettings.h>

Inheritance diagram for HSettings:

HFile HObjNoCopy HObj

Detailed Description

Application settings are managed bh the HSettings class through Key:Value pairs. The data repository created by this class is persistent, in that it can be written out and read in from a .ini file external to the application; it is also non-structured, in that every element within the data store consists of only a key and a value; the key is any unique string, while the value can be any string. Since both a key and a value are required, a single element is also called a key/value pair. To keep the framework flexible, naming conventions for keys are left the developer.

To write out the key/value pairs to a file, the HSettings class is derived from the HFile class, which wraps the UNIX standard file I/O routines and provides a little better error handing. The key/value pairs are written out to file using the format "key=value", which makes them easy to read and edit; this is also the format used by decades of ".ini" files. Future versions of the HSettings class will be able to categorize key/value pairs by using the [section] label, but for now they are written out to the file in alphabetical order.

One issue that must be dealt with is how to handle a setting that is missing; this is particularly crucial when an application is started for the first time, as the settings file may not exist at all! The HSettings class deals with missing values by requiring all Get() operations to specify a default value; if the setting isn't already present, then it is automatically added with the default value. Either way, calling the HSettings::Get() method is guaranteed to always return a value; HSettings does not, however, make any attempt to determine if the value is reasonable. In a solid and robust design, the value of every application setting should be sanity-checked before actually being acted upon...just in case.

Definition at line 53 of file HSettings.h.

Public Member Functions

ErrCode Load (const HFilename &fs)
 Read in settings from an .ini file.
ErrCode Remove (StringPtr pstrKey)
 Removes a setting from the file return NO_ERROR on success, error code otherwise.
ErrCode Save (const HFilename &fs)
 Saves the settings to an .ini file.
int32 Get (StringPtr pstrKey, int32 nDefault)
 Get an integer setting.
StringPtr Get (StringPtr pstrKey, StringPtr pstrDefault)
 Get a string setting.
bool GetFlag (StringPtr pstrKey, const bool bDefault)
 Get a boolean setting.
int32 Set (StringPtr pstrKey, const int32 nValue)
 Set an integer setting.
StringPtr Set (StringPtr pstrKey, StringPtr pstrValue)
 Set a string setting.
bool SetFlag (StringPtr pstrKey, const bool bValue)
 Set a boolean flag.
bool IsEmpty (void) const
 Evaluates if the settings dictionary is empty.
bool IsNotEmpty (void) const
 Evaluates if the settings dictionary is not empty.
ErrCode RemoveAll (void)
 Deletes ALL key:value pairs.

Protected Member Functions

void parseLine (const uint32 uLine, TextPtr pszLine)
 Parse a line of text.
ErrCode writeToFile (void)
 Writes out the settings to a file.
StringPtr getValue (StringPtr pstrKey) const
 Gets a key:value pair from the underlying tree.
ErrCode setValue (StringPtr pstrKey, StringPtr pstrValue)
 Sets a key/value pair in the data store.

Protected Attributes

bool m_bDirty
 True if any settings have changed.
HSettingsMap m_map

Member Function Documentation

ErrCode HSettings::Load (  const HFilename &  fs  ) 
 

This method reads the contents of an .ini file; if the file is not found or cannot be parsed, a new data store is created.

Returns:
NO_ERROR on success, error code otherwise
Parameters:
fs Fully-qualified file name to read settings from

Definition at line 87 of file HSettings.h.

ErrCode HSettings::Remove (  StringPtr  pstrKey  ) 
 

Parameters:
pstrKey Key value to remove

Definition at line 114 of file HSettings.h.

ErrCode HSettings::Save (  const HFilename &  fs  ) 
 

This method writes out the current settings to an .ini file.

Returns:
NO_ERROR on success, error code otherwise
Parameters:
fs Fully-qualified file name to write settings to

Definition at line 135 of file HSettings.h.

void HSettings::parseLine (  const uint32  uLine,
TextPtr  pszLine
)  [protected]
 

Parameters:
uLine The line number (used to report errors)
pszLine Pointer to the line of text to parse

Definition at line 163 of file HSettings.h.

ErrCode HSettings::writeToFile (  void   )  [protected]
 

Returns:
Always NO_ERROR

Definition at line 198 of file HSettings.h.

int32 HSettings::Get (  StringPtr  pstrKey,
int32  nDefault
) 
 

Returns:
Numeric value of setting
Parameters:
pstrKey Path to setting key
nDefault Default value

Definition at line 225 of file HSettings.h.

StringPtr HSettings::Get (  StringPtr  pstrKey,
StringPtr  pstrDefault
) 
 

Returns:
Setting value
Parameters:
pstrKey Path to setting key
pstrDefault Default value

Definition at line 242 of file HSettings.h.

bool HSettings::GetFlag (  StringPtr  pstrKey,
const bool  bDefault
) 
 

Reads a boolean setting from the data repository. The following values are all considered true (case insensitive):

  • true
  • .T.
  • yes
  • any non-zero integer

Returns:
True or false
Parameters:
pstrKey Path to setting key
bDefault Default value

Definition at line 267 of file HSettings.h.

int32 HSettings::Set (  StringPtr  pstrKey,
const int32  nValue
) 
 

Returns:
New value
Parameters:
pstrKey Path to setting
nValue Default value

Definition at line 287 of file HSettings.h.

StringPtr HSettings::Set (  StringPtr  pstrKey,
StringPtr  pstrValue
) 
 

Returns:
New value
Parameters:
pstrKey Path to setting
pstrValue Value

Definition at line 304 of file HSettings.h.

bool HSettings::SetFlag (  StringPtr  pstrKey,
const bool  bValue
) 
 

Saves a boolean setting to the data repository.

Returns:
True or false
Parameters:
pstrKey Path to setting key
bValue Default value

Definition at line 321 of file HSettings.h.

StringPtr HSettings::getValue (  StringPtr  pstrKey  )  const [protected]
 

Returns:
StringPtr to value if found, NULL otherwise
Parameters:
pstrKey Key to search for

Definition at line 336 of file HSettings.h.

ErrCode HSettings::setValue (  StringPtr  pstrKey,
StringPtr  pstrValue
)  [protected]
 

Returns:
NO_ERROR on success, error code otherwise
Parameters:
pstrKey Key
pstrValue Value

Definition at line 362 of file HSettings.h.

bool HSettings::IsEmpty (  void   )  const
 

Returns:
True if no settings are present, false otherwise

Definition at line 385 of file HSettings.h.

bool HSettings::IsNotEmpty (  void   )  const
 

Returns:
True if at least one setting is present, false otherwise

Definition at line 389 of file HSettings.h.

ErrCode HSettings::RemoveAll (  void   ) 
 

Returns:
NO_ERROR on success, error code otherwise

Definition at line 393 of file HSettings.h.

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

2006.01.09-16:37