XMLPort

Description

XMLPort.h is a compilation of macros and classes for easy XML parsing. Every object starting with BaseObject has some attributes to be set, either by a default value or specified in the XML level file. The Loader? parses the file, creates the main objects an passes the attributes and subobjects to their XMLPort function.

Inside of this function, one macro for every parameter and every possible subobject defines how to assign the loaded values to the newly created object.

The XMLPort Function

This is how an empty XMLPort function looks like:

*.h file:

class SomeClass : public BaseClass
{
    public:
        virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
};

*.cc file:

void SomeClass::XMLPort(Element& xmlelement, XMLPort::Mode mode)
{
    SUPER(SomeClass, XMLPort, xmlelement, mode);
}

xmlelement is a container, containing all attributes and subobjects passed to this class.
mode says if we're loading new objects from a file or saving existing objects to a file.
SUPER is a macro, see Super for more information.

Important: XMLPort is a virtual function.

Parameters

General

To load parameters like the name of an object, you need three things:

1. A set-function in your class to set the parameter:

       void setName(const std::string& name);
   

2. A get-function returning the parameter:

       const std::string& getName() const;
   

3. A call to the XMLPortParam macro in XMLPort:

   void SomeClass::XMLPort(Element& xmlelement, XMLPort::Mode mode)
   {
       SUPER(SomeClass, XMLPort, xmlelement, mode);
   
       XMLPortParam(SomeClass, "name", setName, getName, xmlelement, mode);
   }
   

To create an instance of SomeClass and set the parameter name, write the following text into the XML file:

<SomeClass name="funny_name" />

XMLPortParam has the following form:

• XMLPortParam(classname, "param-name", set-function, get-function, xmlelement, mode)

xmlelement and mode are received by the XMLPort function.

Ambiguity

Sometimes the name of the set-function in XMLPortParam is ambiguous, because the function is overloaded.

Example:

    void setPosition(float x, float y, float z);
    void setPosition(const Vector3& position);

In this case, the following code will fail:

XMLPortParam(SomeClass, "position", setPosition, getPosition, xmlelement, mode);
// Error: setPosition is ambiguous

The problem can be solved by using XMLPortParamTemplate:

// If you want to use the first variant with three floats:
XMLPortParamTemplate(SomeClass, "position", setPosition, getPosition, xmlelement, mode, float, float, float);

// If you want to use the second variant with a Vector3:
XMLPortParamTemplate(SomeClass, "position", setPosition, getPosition, xmlelement, mode, const Vector3&);

As you can see, the type(s) of the function arguments are just appended at the end of the macro.

Loadonly

In some special cases you don't want to save an existing parameter to the XML file. This could be the case if there are several dependend functions to set one parameter, but only one is needed to save the parameter.

Example: Rotation - you could pass a Quaternion or three angles or something else, but you only have to save the Quaternion. The three angles would then be stated as "loadonly":

XMLPortParamLoadOnly(SomeClass, "three-angles", setAngles, xmlelement, mode);

As you can see, there's no get-function.

Note: There is also a related macro called XMLPortParamLoadOnlyTemplate used to avoid ambiguity (see the chapter above).

Extern parameters

Sometimes you have a memberobject in you class which has a parameter that you want to set through XMLPort in your own class.

Example:

class Position
{
    public:
        void setPosition(const Vector3& position);
        const Vector3& getPosition() const;

    private:
        Vector3 position_;
};

class SomeClass
{
    public:
        virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);

    private:
        Position position_;
}

Of course you could just add two functions setPosition and getPosition to SomeClass, but that would be a bit stupid. A more elegant way is to use XMLPortParamExtern:

XMLPortParamExtern(SomeClass, Position, this->position_, "position", setPosition, getPosition, \
                                                                             xmlelement, mode);

Note: The second and the third argument are new: Position is the class of the extern parameter, this→position_ is the object. The other arguments stay the same, but the set- and get-function are now functions of Position instead of SomeClass and therefore we don't have to implement two useless functions.

Note: There is also a related macro called XMLPortParamExternTemplate used to avoid ambiguity (see the chapter above).

Objects

General

To connect objects, you have to put one object into another object in the XML file:

<SomeClass param=...>
  <connected-objects>
    <OtherClass param=... />
    <OtherClass param=... />
    <OtherClass param=... />
  </connected-objects>
  <more-objects>
    <DifferentClass param=... />
    <DifferentClass param=... />
  </more-objects>
</SomeClass>

In this example, we create one instance of SomeClass and connect three instances of OtherClass and two instances of DifferentClass to it.

To let the instance of SomeClass know there are some connected objects, we have to pass them to a function of SomeClass. This can be achieved by using XMLPortObject:

void SomeClass::XMLPort(Element& xmlelement, XMLPort::Mode mode)
{
    SUPER(SomeClass, XMLPort, xmlelement, mode);

    XMLPortObject(SomeClass, OtherClass, "connected-objects", connectObject, getConnectedObject, \
                                                                                xmlelement, mode);
    XMLPortObject(SomeClass, DifferentClass, "more-objects", addDifferentObject, getDifferentObject, \
                                                                                xmlelement, mode);
}

Note: We used XMLPortObject two times because we have two subsections with different types of connected objects.

XMLPortObject has the following form:

• XMLPortObject(classname, objectclass, sectionname, loadfunction, savefunction, xmlelement, mode)

objectclass is the class of the conneted objects in the specified subsection.
sectionname is the name of the subsection.

Important: If sectionname is an empty string (""), no subsection is used, so you can put sub-objects directly into the base object.

The set- and the get-function must have the following form:

• void set-function(objectclass* object);
• const objectclass* get-function(unsigned int index) const;

The set-function just passes the pointer of the connected object.
The get-function returns a different pointer for each index, starting with zero. If all pointers were returned, the get-function returns a NULL pointer and the process stops.

Note: There is also a related macro called XMLPortObjectTemplate used to avoid ambiguity (see the chapter above).

Extended

There is an extended version of the XMLPortParam macro, taking two additional arguments:

• XMLPortObjectExtended(classname, objectclass, sectionname, loadfunction, savefunction, xmlelement, mode, bApplyLoaderMask, bLoadBefore)

If bApplyLoaderMask is true, a subobject gets only created and connected if it's class is included in the mask of the Loader?. This argument is usually false because not connecting a subobject might damage the base-object, although the base-object IS included in the Loaders mask and should therefore not be touched.

If bLoadBefore is true, the subobject will get connected after all parameters (and subobjects of the subobject) are completely loaded. This argument is usually true because we might use the connected object already in the set-function. If the subobject is not already loaded at this point, this could cause trouble.

Note: There is also a related macro called XMLPortObjectExtendedTemplate used to avoid ambiguity (see the chapter above).