Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

plist::Dictionary Class Reference

#include <plist.h>

Inheritance diagram for plist::Dictionary:

Inheritance graph
[legend]
List of all members.

Detailed Description

Maintains a set of (key,value) pairs, where a value can be any subclass of ObjectBase.

This class supports callbacks upon modification through the use of the DictionaryListener interface. Note that we only store a pointer to the listener list, which is typically unallocated when no listeners are active. This should ensure minimal memory usage per object, as well as support safe storage of plist objects in inter-process shared memory regions.

If you are using these in a shared memory region, just be sure that only the process with listeners does any and all modifications, and that it unsubscribes before detaching from the region (or else destroys the region itself)

There isn't a callback if entries themselves are modified, only when new entries are added, or old ones removed. If you want to know any time any aspect of any entry is modified, listen for the add and remove callbacks, and then add yourself as a listener to each entry individually.

Definition at line 118 of file plist.h.

Public Member Functions

 Dictionary ()
 constructor
 Dictionary (const Dictionary &d)
 copy constructor (don't assign listeners)
Dictionaryoperator= (const Dictionary &d)
 assignment (don't assign listeners)
virtual ~Dictionary ()
 destructor
void addEntry (const std::string &name, ObjectBase &val)
 insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but gives a warning)
void addEntry (const std::string &name, ObjectBase &val, const std::string &comment)
 insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but gives a warning)
void setEntry (const std::string &name, ObjectBase &val)
 replaces previous entry of the same name, or adds it if it doesn't exist; use addEntry if you want to assert that the name does not already exist
void setComment (const std::string &name, const std::string &comment)
 replaces previous comment for name, or adds it if it doesn't already exist (can preceed actual entry!)
const std::string & getComment (const std::string &name) const
 returns comment retrieved from loaded file, or any subsequent call to setComment
void removeEntry (const std::string &name)
 remove the entry with key name
ObjectBasefindEntry (const std::string &name) const
 return the value of the key name, or NULL if it doesn't exist
void LoadXML (xmlNode *node)
 This is called when the subclass needs to update its values from those values in the parse tree.
void SaveXML (xmlNode *node) const
 This is called when XMLLoadSave needs to have the subclass update values in the tree currently in memory -- may already be filled out by previous contents.
void setUnusedWarning (bool b)
 set warnUnused
bool getUnusedWarning ()
 returns warnUnused
virtual void addDictionaryListener (DictionaryListener *vl)
 get notified of changes; be sure to call removeValueListener before destructing vl!
virtual void removeDictionaryListener (DictionaryListener *vl)
 no longer take notification of changes to this object's value

Protected Types

typedef std::map< std::string,
ObjectBase * > 
dict_t
 shorthand for the type of dict
typedef std::map< std::string,
std::string > 
comments_t
 shorthand for the type of comments

Protected Member Functions

virtual void fireEntryAdded (ObjectBase &val)
 run through dictionaryListeners, calling DictionaryListener::plistDictionaryEntryAdded(*this,val)
virtual void fireEntryRemoved (ObjectBase &val)
 run through dictionaryListeners, calling DictionaryListener::plistDictionaryEntryRemoved(*this,val)
unsigned int getLongestKeyLen () const
 return the length of the longest key for formatting purposes

Protected Attributes

std::list< DictionaryListener * > * dictionaryListeners
 stores a list of the current listeners
bool warnUnused
 if true (the default) LoadXML will give warnings if there are unused entries in the node it is passed
dict_t dict
 storage of entries -- mapping from keys to value pointers
comments_t comments
 storage of entry comments -- mapping from keys to help text comments for manual editing or user feedback

Friends

std::ostream & operator<< (std::ostream &os, const Dictionary &d)
 provides textual output


Member Typedef Documentation

typedef std::map<std::string,std::string> plist::Dictionary::comments_t [protected]
 

shorthand for the type of comments

Definition at line 175 of file plist.h.

typedef std::map<std::string,ObjectBase*> plist::Dictionary::dict_t [protected]
 

shorthand for the type of dict

Definition at line 170 of file plist.h.


Constructor & Destructor Documentation

plist::Dictionary::Dictionary  )  [inline]
 

constructor

Definition at line 122 of file plist.h.

plist::Dictionary::Dictionary const Dictionary d  )  [inline]
 

copy constructor (don't assign listeners)

Definition at line 124 of file plist.h.

plist::Dictionary::~Dictionary  )  [virtual]
 

destructor

Definition at line 95 of file plist.cc.


Member Function Documentation

void plist::Dictionary::addDictionaryListener DictionaryListener vl  )  [virtual]
 

get notified of changes; be sure to call removeValueListener before destructing vl!

Definition at line 313 of file plist.cc.

void plist::Dictionary::addEntry const std::string &  name,
ObjectBase val,
const std::string &  comment
 

insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but gives a warning)

Definition at line 111 of file plist.cc.

void plist::Dictionary::addEntry const std::string &  name,
ObjectBase val
 

insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but gives a warning)

Definition at line 100 of file plist.cc.

ObjectBase * plist::Dictionary::findEntry const std::string &  name  )  const
 

return the value of the key name, or NULL if it doesn't exist

Definition at line 129 of file plist.cc.

Referenced by findEntry().

void plist::Dictionary::fireEntryAdded ObjectBase val  )  [protected, virtual]
 

run through dictionaryListeners, calling DictionaryListener::plistDictionaryEntryAdded(*this,val)

Definition at line 334 of file plist.cc.

void plist::Dictionary::fireEntryRemoved ObjectBase val  )  [protected, virtual]
 

run through dictionaryListeners, calling DictionaryListener::plistDictionaryEntryRemoved(*this,val)

Definition at line 344 of file plist.cc.

const std::string & plist::Dictionary::getComment const std::string &  name  )  const
 

returns comment retrieved from loaded file, or any subsequent call to setComment

Definition at line 123 of file plist.cc.

unsigned int plist::Dictionary::getLongestKeyLen  )  const [protected]
 

return the length of the longest key for formatting purposes

Definition at line 302 of file plist.cc.

Referenced by getLongestKeyLen(), and plist::operator<<().

bool plist::Dictionary::getUnusedWarning  )  [inline]
 

returns warnUnused

Definition at line 149 of file plist.h.

void plist::Dictionary::LoadXML xmlNode node  )  [virtual]
 

This is called when the subclass needs to update its values from those values in the parse tree.

node is the current node in the tree -- it may be the root, but it may also be a subnode within the tree if a recursive structure is used

Implements XMLLoadSave.

Definition at line 150 of file plist.cc.

Dictionary& plist::Dictionary::operator= const Dictionary d  )  [inline]
 

assignment (don't assign listeners)

Definition at line 126 of file plist.h.

void plist::Dictionary::removeDictionaryListener DictionaryListener vl  )  [virtual]
 

no longer take notification of changes to this object's value

Definition at line 321 of file plist.cc.

void plist::Dictionary::removeEntry const std::string &  name  )  [inline]
 

remove the entry with key name

Definition at line 141 of file plist.h.

void plist::Dictionary::SaveXML xmlNode node  )  const [virtual]
 

This is called when XMLLoadSave needs to have the subclass update values in the tree currently in memory -- may already be filled out by previous contents.

node is the current node in the tree -- it may be the root, but it may also be a subnode within the tree if a recursive structure is used

Implements XMLLoadSave.

Definition at line 189 of file plist.cc.

void plist::Dictionary::setComment const std::string &  name,
const std::string &  comment
[inline]
 

replaces previous comment for name, or adds it if it doesn't already exist (can preceed actual entry!)

Definition at line 137 of file plist.h.

Referenced by LoadXML().

void plist::Dictionary::setEntry const std::string &  name,
ObjectBase val
[inline]
 

replaces previous entry of the same name, or adds it if it doesn't exist; use addEntry if you want to assert that the name does not already exist

Definition at line 135 of file plist.h.

void plist::Dictionary::setUnusedWarning bool  b  )  [inline]
 

set warnUnused

Definition at line 148 of file plist.h.


Friends And Related Function Documentation

std::ostream& operator<< std::ostream &  os,
const Dictionary d
[friend]
 

provides textual output

Definition at line 354 of file plist.cc.


Member Data Documentation

comments_t plist::Dictionary::comments [protected]
 

storage of entry comments -- mapping from keys to help text comments for manual editing or user feedback

not every key necessarily has a comment!

Definition at line 178 of file plist.h.

Referenced by addEntry(), getComment(), operator=(), SaveXML(), and setComment().

dict_t plist::Dictionary::dict [protected]
 

storage of entries -- mapping from keys to value pointers

Definition at line 172 of file plist.h.

Referenced by addEntry(), findEntry(), getLongestKeyLen(), LoadXML(), plist::operator<<(), operator=(), removeEntry(), SaveXML(), and setEntry().

std::list<DictionaryListener*>* plist::Dictionary::dictionaryListeners [protected]
 

stores a list of the current listeners

Definition at line 162 of file plist.h.

Referenced by addDictionaryListener(), fireEntryAdded(), fireEntryRemoved(), removeDictionaryListener(), and ~Dictionary().

bool plist::Dictionary::warnUnused [protected]
 

if true (the default) LoadXML will give warnings if there are unused entries in the node it is passed

Definition at line 167 of file plist.h.

Referenced by getUnusedWarning(), LoadXML(), operator=(), SaveXML(), and setUnusedWarning().


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

Tekkotsu v2.4.1
Generated Tue Aug 16 16:35:14 2005 by Doxygen 1.4.4