XMLPort

TracNav(TracNav/TOC_Development)?

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