derivedSRUserExt.h

Go to the documentation of this file.

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

#ifndef DerivedSRUserExtension_H_
#define DerivedSRUserExtension_H_

#include "vrfobjparam/vrfSRUserExt.h"
#include "vrfutil/rwString.h"

//class DerivedSRUserExtension:
//
//Instances of DerivedSRUserExtension are an example of an extension to 
//a base state repository class.  It provides a way to extend an entity's state
//information independent at a lower level in the state repository hierarchy.
//All entities in VR-Forces have at a minimum a DtVrfObjectStateRepsitory, which
//can be extended in this way.  By extending a state repository through the
//DtVrfStateRepostioryUserExtension class, you don't have to extend multiple 
//leaf-level state repository classes to add the same kind of extension 
//to different kinds of entities (e.g. ground vehicles and air entities, both
//of which have different derived state repository classes).
//
//A state repository extension object (DtVrfStateRepositoryUserExtension) can be
//initialized from a parameter database, and then saved/restored as part of an 
//entity's state in an order of battle file.
//
//This example of a user-defined state repository extensions class contains a 
//single new data member, myTag (a new kind of identifier).  The myTag member
//variable is a readable, writeable string (DtRwString).  myTag is registered 
//with the name "my-tag" in this class' constructor.
//
//The class returns a new type string "my-state-repository-user-extension".
//This is the key that gets registered with the factory so VR-Forces will
//know how to create an instance of this class when it encounters it in
//a parameter database file.  The configuration of an instance of this type of
//state repository extension in a parameter database file (an .ope file) would
//look something like this:
//
//(state-repository-extension-type  "my-state-repository-user-extension")
//(user-extension
//  (my-tag "some-useful-info")
//)
//
//At runtime, you can access the state repository extension through the 
//entity's state repository member, e.g.
//
//DtVrfObject* entity;
//DerivedSRUserExtension* userSRExtension = 
//dynamic_cast<DerivedSRUserExtension*>(entity->vrfState()->userExtension());

class DerivedSRUserExtension : public DtVrfStateRepositoryUserExtension
{
public:

   //constructor
   DerivedSRUserExtension(DtVrfObjectStateRepository* stateRepository,
      const DtString& rwName = DtString::nullString(),  
      DtReaderWriterRegistry* parentRegistry = 0);

   //copy constructor
   DerivedSRUserExtension(DtVrfObjectStateRepository* stateRepository,
      const DerivedSRUserExtension& orig,
      const DtString& rwName = DtString::nullString(), 
      DtReaderWriterRegistry*  parentRegistry = 0);

   //assignment
   const DerivedSRUserExtension& operator=(
      const DerivedSRUserExtension& orig);

   //destructor
   virtual ~DerivedSRUserExtension();

   //Note you must implement the clone function in derived classes to ensure
   //that this data is initialized from the parameter database correctly.
   virtual DtVrfStateRepositoryUserExtension* clone(
      DtVrfObjectStateRepository* stateRepository,
      const DtString& name, 
      DtReaderWriterRegistry* parentRegistry = NULL) const;

   //Type of extension object to create.  Existing type(s) are defined in
   //derivedSRUserExtTypes.h.  Our new class returns the string
   //"my-state-repository-user-extension".  This is the string that must be
   //registered with the factory that creates these objects, and specified in
   //in the parameter database file when we want one of these classes instantiated.
   virtual DtString type() const;

   //Called after object has been created by the DtVrfObjectStateRepository class.
   virtual void init();

   //Specific user data extensions.  In this case, its a readable writeable string
   //with the DtReaderWriter name 'my-tag'.
   virtual void setTag(const DtString& tag);
   virtual const DtString& tag() const;

   //Returns newly created instance of this class.
   static DtVrfStateRepositoryUserExtension* create(
      DtVrfObjectStateRepository* stateRepository,
      const DtString& rwName = DtString::nullString(),  
      DtReaderWriterRegistry* parentRegistry = 0);

protected:

   DtRwString myTag;
};

#endif