include/makSettingsManager/settingsManager.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2008 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
/*******************************************************************************
** $RCSfile: settingsManager.h,v $ $Revision: 1.4 $ $State: Exp $
*******************************************************************************/

// \file settingsManager.h
// \brief Manages settings saved out in an XML file
// The DtSettingsManager contains DtSettingsObjects which are seralized into
// a settings file using boost::serialize. This manager is not a data storage
// class -- it simply maintains a copy on behalf of a client which provides
// a setting. Such clients are called producers and provide functions which
// the manager can use to get the latest value. Values are only updated upon
// lookup and immediately before the file is written out to disk. Producers
// are not required -- independent settings can also be added to the manager.
// Changes to settings objects can be tracked by registering as a consumer
// for a given object.

#ifndef settingsManager_H_
#define settingsManager_H_

#include "makSettingsManager/settingsObject.h"

#include "vlutil/vlFilename.h"

#include <map>

class DtSettingsObjectFactory;

// Definition for producer functions which are used with registerProducer
typedef void (*DtSettingsProducerFcn)(DtSettingsObject* object, void* usr);

// Holds producer details
struct DtSettingsProducer
{
   std::string type;
   DtSettingsProducerFcn producerFcn;
   void* usr;
};

// Definition for map of producers
typedef std::map<std::string, DtSettingsProducer> DtSettingsProducersMap;

// Definition for comsumer functions which are used with registerConsumer
typedef void (*DtSettingsConsumerFcn)(const DtSettingsObject* object, 
   void* usr);

// Holds consumer details
struct DtSettingsConsumer
{
   DtSettingsConsumerFcn consumerFcn;
   void* usr;
};

// Definition for multi-map of consumers
typedef std::multimap<std::string, DtSettingsConsumer>
   DtSettingsConsumersMultiMap;

// Definition for map of DtSettingsObjects
typedef std::map<std::string, DtSettingsObject*> DtSettingsMap ;

#include "makSettingsManager/makSettingsManagerDefines.h"
class DT_DLL_makSettingsManager DtSettingsManager
{
public:   
   // Constructor
   DtSettingsManager(std::string filename);
 
   // Destructor
   ~DtSettingsManager();

   // Calls read()
   virtual void init();
   
   // Opens and parses the settings file
   virtual bool read();
   
   // Updates all settings objects via their associated producer functions and
   // then writes out the settings file.
   virtual bool write();

   // DtSettingsObjectFactory
   static DtSettingsObjectFactory* factory();
   static void setFactory(DtSettingsObjectFactory* factory);
   
   // \brief Returns a pointer to the named settings object from the map.
   // If the object does not exist but a producer has been registered for it,
   // a new instance of the object will be created and returned.
   // If the object has been read in from the settings file but does not yet 
   // have a producer associated with it, its value will still be returned.
   // If the object does not exist in the map and there is no producer
   // associated with it, null (0) is returned.
   // Note that the return type is const because clients should only write 
   // settings data via their DtSettingsProducerFcn which they register with
   // registerProducer. 
   virtual const DtSettingsObject* lookupSetting(std::string name);

   // Updates an existing DtSettingsObject from the one provided by using
   // its setFrom method. If there is no DtSettingsObject in the DtSettingsMap
   // whose name corresponds to the name of the object provided, or if their
   // types do not match, false is returned and the setting is left unchanged.
   virtual bool setSetting(const DtSettingsObject* settingsObject);

   // Returns the key list of the settings map.
   virtual std::list<std::string>  settingsMapKeys();

   // \brief Registers a producer function as the source for the given setting
   // Associates the given DtSettingsProducerFcn with the given settings name.
   // All three arguments are copied into a DtSettingsProducer which is stored
   // in myProducersMap.
   // Whenever lookupSetting is called, this function will be used to update
   // the settings object with the most current data from the producer before
   // it is returned to the caller. If a producer with the same name is
   // already registered in myProducersMap, the associated settings object
   // in mySettingsMap is no longer considered valid and will be deleted.
   virtual void registerProducer(std::string type, std::string name,
      DtSettingsProducerFcn producerFcn, void* usr = 0);
   virtual void unregisterProducer(std::string type, std::string name,
      DtSettingsProducerFcn producerFcn, void* usr = 0);

   // DtSettingsConsumerFcn's are called whenever a named DtSettingsObject
   // changes. The arguments are copied into a DtSettingsConsumer used to
   // update the myConsumersMultiMap. 
   // @{
   virtual void registerConsumer(std::string name,
      DtSettingsConsumerFcn consumerFcn, void* usr = 0);  
   virtual void unregisterConsumer(std::string name,
      DtSettingsConsumerFcn consumerFcn, void* usr = 0);
   // @}

   // Registers an independent setting that does not have an associated
   // producer function. Independent settings are generally only used when
   // a given setting will never be associated with other settings grouped
   // into a subclass of DtSettingsObject.
   // @{
   virtual void addIndependentBool(std::string name, bool value);
   virtual void addIndependentInt(std::string name, int value);
   virtual void addIndependentDouble(std::string name, double value);
   virtual void addIndependentString(std::string name, std::string value);
   // @}

protected:
   // Settings file to read/write
   std::string myFilename;
   
   // Map of DtSettingsObjects
   DtSettingsMap mySettingsMap;
   
   // Map of DtSettingsProducers
   DtSettingsProducersMap myProducersMap;
   
   // Map of DtSettingsConsumers
   DtSettingsConsumersMultiMap myConsumersMultiMap;
   
   // DtSettingsObjectFactory
   static DtSettingsObjectFactory* theSettingsObjectFactory;
};

#endif