---

Object Interface Macros

SimData defines several macros that are used to create interfaces to object classes. Interfaces are defined inside of the corresponding object class declaration, and contain information about both the inheritance hierarchy and the object class member variable that can be assigned from external data sources.

Interface should be defined in a public section of the enclosing Object class. The general structure in a "BEGIN" macro, followed by a number of data member declarations, terminated by an "END" macro.

There are several forms of "BEGIN" macro, depending on the circumstances:

• BEGIN_SIMDATA_XML_INTERFACE(class) should be used for non-virtual Object classes, when none of the parent classes define interfaces.

• EXTEND_SIMDATA_XML_INTERFACE(class, parent) should be used for non-virtual Object classes with base classes that define interfaces. The parent parameter is the first class up the inheritance chain that defines an interface, which is often but not necessarily one of the immidiate base classes.

• BEGIN_SIMDATA_XML_VIRTUAL_INTERFACE(class) is the same as BEGIN_SIMDATA_XML_INTERFACE except that it does not define methods for dynamic object creation. It should be used for abstract classes (which declare one or more pure virtual methods).

• EXTEND_SIMDATA_XML_VIRTUAL_INTERFACE(class, parent) is the same as EXTEND_SIMDATA_XML_INTERFACE except that it does not define methods for dynamic object creation. It should be used for abstract classes (which declare one or more pure virtual methods).

Between the "BEGIN" and "END" macros, include SIMDATA_XML(name, member, required) and SIMDATA_BIT(name, member, bit, required) macros to bind class member variables to string identifiers which are used to assign values in external data files. The member parameter must include the class-quialified member name. The required field specifies whether a particular variable must be set in the external data source. If required is false, you must assign a reasonable default value in the class constructor. The bit parameter, used by the SIMDATA_BIT macro, sets a mask for assigning boolean values to specific bits in an integer member variable (e.g. char, int, unsigned short, etc.) Each bit acts as a distinct variable in the source data file, and SimData takes care of packing the bits correctly into the associated member variable.

Finally, the "END" macro is always END_SIMDATA_XML_INTERFACE.

Here are a couple examples:

  class myclass: public simdata::Object {
    std::string name;
    simdata::Real size;
  public:
    ...
    BEGIN_SIMDATA_XML_INTERFACE(myclass)
      SIMDATA_XML("name", myclass::name, true)
      SIMDATA_XML("size", myclass::size, true)
      ...
    END_SIMDATA_XML_INTERFACE
    ...
  };

and

  class Monster: public ScaryAnimal {
  public:
    ...
    EXTEND_SIMDATA_XML_INTERFACE(Monster, ScaryAnimal)
      SIMDATA_XML("count", Monster::count, false)
      SIMDATA_BIT("has_ears", Monster::traits, 0x01, true)
      SIMDATA_BIT("has_eyes", Monster::traits, 0x02, true)
      SIMDATA_BIT("has_nose", Monster::traits, 0x04, true)
      SIMDATA_BIT("has_toes", Monster::traits, 0x08, true)
      ...
    END_SIMDATA_XML_INTERFACE
    ...
  private:
    int count;
    unsigned char traits;
  };

Interface classes must be registered with SimData. To do so, use the SIMDATA_REGISTER_INTERFACE(class) macro in the source file for the class. Since this macro creates an instance of the interface class, it should not be used in a header file. The SIMDATA_REGISTER_INNER_INTERFACE(prefix, class) macro serves the same purpose, but works for classes declared inside a named scope (e.g. a namespace or inner class).

The examples above would be registered by

  SIMDATA_REGISTER_INTERFACE(myclass);
  SIMDATA_REGISTER_INTERFACE(Monster);

---

SimData version pre-0.4.0. For more information on SimData, visit the SimData Homepage. Generated on Tue Oct 14 12:06:42 2003, using Doxygen 1.2.18.