PreferenceHandler Class Reference

The PreferenceHandler class provides an easy mechanism to store and retrieve key/value pairs of different types (bool, int, float and string). More...

#include <PreferenceHandler.h>

Collaboration diagram for PreferenceHandler:

[legend]List of all members.


Public Member Functions
	PreferenceHandler (std::string path)
	Initializes a new PreferenceHandler backed by the file pointed to by path.
	~PreferenceHandler ()
	Cleans up after this PreferenceHandler object, automatically synching.
int	getError ()
	Return the last error that occurred.
bool	boolForKey (const std::string &key)
	Invokes stringForKey() with key.
bool	boolForKey (const char *key)
float	floatForKey (const std::string &key)
	Invokes stringForKey() with key.
float	floatForKey (const char *key)
int	intForKey (const std::string &key)
	Invokes stringForKey() with key.
int	intForKey (const char *key)
std::string	stringForKey (const std::string &key)
	Returns the string associated with key.
std::string	stringForKey (const char *key)
void	setBoolForKey (const bool b, const std::string &key)
	Sets the value of the key/value pair to a string representation of true or false, depending on b.
void	setBoolForKey (const bool b, const char *key)
void	setFloatForKey (const float f, const std::string &key)
	Sets the value of the key/value pair to a string representation of the float value f.
void	setFloatForKey (const float f, const char *key)
void	setIntForKey (const int i, const std::string &key)
	Sets the value of the key/value pair to a string representation of the int value i.
void	setIntForKey (const int i, const char *key)
void	setStringForKey (const std::string &str, const std::string &key)
	Sets the value of the key/value pair to a string.
void	setStringForKey (const char str, const char key)
bool	synchronize ()
	Saves any modifications to the preference file or updates the values in memory with values on disk, if they where not modified.
Static Public Member Functions
static void	Init (std::string path)
	Initialize a standard PreferenceHandler, backed by a file.
static void	Clean ()
	Clean up after the standard PreferenceHandler.
static PreferenceHandler *	StandardPreferenceHandler ()
	Get the standard PreferenceHandler.
static void	ExpandTildeInPath (std::string &path)
	Expands ~ and ~USR patterns in path names.
Private Member Functions
xmlNodePtr	getNodeForKey (const std::string &key)
xmlNodePtr	addNewKey (const std::string &key)
Private Attributes
std::string	path
xmlDocPtr	doc
int	error
bool	modified
Static Private Attributes
static PreferenceHandler *	stdPH

Detailed Description

The PreferenceHandler class provides an easy mechanism to store and retrieve key/value pairs of different types (bool, int, float and string).

The PreferenceHandler stores preferences in XML format. You can have multiple PreferenceHandlers working on different files at the same tim but more common is probably to install a standard global PreferenceHandler. This can be done by invoking the static method Init() with a path to the XML file. The standard PreferenceHandler can then be retreived using the static function StandardPreferenceHandler().

Example usage: At application initialization the programmer would initialize the PreferenceHandler.

 PreferenceHandler::Init("~/.myApp.xml");

 //Later the programmer want to reference a setting and checks the 
 //standard PreferenceHandler object for it.

 PreferenceHandler *main = 
               PreferenceHandler::StandardPreferenceHandler();

 if(main->boolForKey("my setting"))
     DoStuff();
 else
     DontDoStuff();

Author:: Daniel Aarno <macbishop@users.sf.net>

Version:: v0.1.0

Constructor & Destructor Documentation

PreferenceHandler::PreferenceHandler ( std::string path )

Initializes a new PreferenceHandler backed by the file pointed to by path.

The file is created if it does not exist.

Parameters:

path

The path to the backing file for this PreferenceHandler, ~ and ~USR are expanded in path, so ~/.myApp.xml is OK.

PreferenceHandler::~PreferenceHandler ( )

Cleans up after this PreferenceHandler object, automatically synching.

Member Function Documentation

xmlNodePtr PreferenceHandler::addNewKey ( const std::string & key ) [private]

bool PreferenceHandler::boolForKey ( const char * key )

bool PreferenceHandler::boolForKey ( const std::string & key )

Invokes stringForKey() with key.

Returns:: true if the value associated with key is a string containing the word true in lowercase or. Otherwise, returns NO.

static void PreferenceHandler::Clean ( ) [static]

Clean up after the standard PreferenceHandler.

This should be called if a call to Init has been made.

static void PreferenceHandler::ExpandTildeInPath ( std::string & path ) [static]

Expands ~ and ~USR patterns in path names.

Parameters:

path

The path to be expanded. NOTE: path will be altered if expansion occurs.

float PreferenceHandler::floatForKey ( const char * key )

float PreferenceHandler::floatForKey ( const std::string & key )

Invokes stringForKey() with key.

Returns a float value if the value associated with key is a string containing a float value. Otherwise, returns 0.0f.

int PreferenceHandler::getError ( ) [inline]

Return the last error that occurred.

xmlNodePtr PreferenceHandler::getNodeForKey ( const std::string & key ) [private]

static void PreferenceHandler::Init ( std::string path ) [static]

Initialize a standard PreferenceHandler, backed by a file.

Parameters:

path

The path to the backing file. Path may contain the ~ character which is automatically expanded.

int PreferenceHandler::intForKey ( const char * key )

int PreferenceHandler::intForKey ( const std::string & key )

Invokes stringForKey() with key.

Returns an int value if the value associated with key is a string containing an int value. Otherwise, returns 0.

void PreferenceHandler::setBoolForKey	(	const bool	b,
		const char *	key
	)

void PreferenceHandler::setBoolForKey	(	const bool	b,
		const std::string &	key
	)

Sets the value of the key/value pair to a string representation of true or false, depending on b.

Invokes setStringForKey() as part of its implementation.

void PreferenceHandler::setFloatForKey	(	const float	f,
		const char *	key
	)

void PreferenceHandler::setFloatForKey	(	const float	f,
		const std::string &	key
	)

Sets the value of the key/value pair to a string representation of the float value f.

Invokes setStringForKey() as part of its implementation.

void PreferenceHandler::setIntForKey	(	const int	i,
		const char *	key
	)

void PreferenceHandler::setIntForKey	(	const int	i,
		const std::string &	key
	)

Sets the value of the key/value pair to a string representation of the int value i.

Invokes setStringForKey() as part of its implementation.

void PreferenceHandler::setStringForKey	(	const char *	str,
		const char *	key
	)

void PreferenceHandler::setStringForKey	(	const std::string &	str,
		const std::string &	key
	)

Sets the value of the key/value pair to a string.

Parameters:

	str	The value to store.
	key	The key associated with the value of str.

static PreferenceHandler* PreferenceHandler::StandardPreferenceHandler ( ) [static]

Get the standard PreferenceHandler.

Returns:: Pointer to the standard PreferenceHandler object or NULL if PreferenceHandler::Init() has not been executed successfully.

std::string PreferenceHandler::stringForKey ( const char * key )

std::string PreferenceHandler::stringForKey ( const std::string & key )

Returns the string associated with key.

An empty string is returned and error is set if no such key/value pair exists.

bool PreferenceHandler::synchronize ( )

Saves any modifications to the preference file or updates the values in memory with values on disk, if they where not modified.

A good strategy is to have synchronize automatically invoked at periodic intervals and use this method only if you cannot wait for the automatic synchronization (for example, if your application is about to exit) or if you want to update user defaults to what is on disk even though you have not made any changes.