XMLPort.h File Reference

Declaration of the XMLPort helper classes and macros. More...

#include "CorePrereqs.h"
#include <cassert>
#include <string>
#include <tinyxml/ticpp.h>
#include "util/Output.h"
#include "util/Exception.h"
#include "util/MultiType.h"
#include "util/OrxAssert.h"
#include "util/StringUtils.h"
#include "class/Identifier.h"
#include "BaseObject.h"
#include "command/Executor.h"

Go to the source code of this file.

Classes
class	orxonox::XMLPortClassObjectContainer< T, O >
class	orxonox::XMLPortClassParamContainer< T >
struct	orxonox::XMLPortClassParamContainer< T >::ParseParams
class	orxonox::XMLPortObjectContainer
class	orxonox::XMLPortParamContainer
class	orxonox::XMLPortVariableHelperClass
	Helper class to load and save simple variables with XMLPort. More...

Namespaces
	orxonox
	Die Wagnis Klasse hat die folgenden Aufgaben:

Macros
#define	XMLPortObject(classname, objectclass, sectionname, loadfunction, savefunction, xmlelement, mode)
	This is the same as XMLPortObjectExtended, but bApplyLoaderMask is false and bLoadBefore is true by default. More...
#define	XMLPortObjectExtended(classname, objectclass, sectionname, loadfunction, savefunction, xmlelement, mode, bApplyLoaderMask, bLoadBefore)
	Declares a possible sub-object that can be added in the XML file. More...
#define	XMLPortObjectExtendedTemplate(classname, objectclass, sectionname, loadfunction, savefunction, xmlelement, mode, bApplyLoaderMask, bLoadBefore, ...)
	This is the same as XMLPortObjectExtended, but you can specify the loadfunction by adding the param types. More...
#define	XMLPortObjectGeneric(containername, classname, objectclass, sectionname, loadexecutor, saveexecutor, xmlelement, mode, bApplyLoaderMask, bLoadBefore)
	Generic XMLPortObject macro, that gets called by all other XMLPortObject macros above. More...
#define	XMLPortObjectTemplate(classname, objectclass, sectionname, loadfunction, savefunction, xmlelement, mode, ...)
	This is the same as XMLPortObject, but you can specify the loadfunction by adding the param types. More...
#define	XMLPortParam(classname, paramname, loadfunction, savefunction, xmlelement, mode)
	Declares an XML attribute with a name, which will be set through load- and savefunctions. More...
#define	XMLPortParamExtern(classname, externclass, object, paramname, loadfunction, savefunction, xmlelement, mode)
	This is the same as XMLPortParam, but for attributes in an extern class. More...
#define	XMLPortParamExternTemplate(classname, externclass, object, paramname, loadfunction, savefunction, xmlelement, mode, ...)
	This is the same as XMLPortParamTemplate, but for extern attributes (see XMLPortParamExtern). More...
#define	XMLPortParamGeneric(containername, classname, objectclass, object, paramname, loadexecutor, saveexecutor, xmlelement, mode)
	This is the generic XMLPort param macro, which is used by all six specialized macros above. More...
#define	XMLPortParamLoadOnly(classname, paramname, loadfunction, xmlelement, mode)
	Declares an XML attribute with a name, which can be set through a loadfunction. More...
#define	XMLPortParamLoadOnlyTemplate(classname, paramname, loadfunction, xmlelement, mode, ...)
	This is the same as XMLPortParamTemplate, but for load-only attributes (see XMLPortParamLoadOnly). More...
#define	XMLPortParamTemplate(classname, paramname, loadfunction, savefunction, xmlelement, mode, ...)
	This is the same as XMLPortParam, but you can set the template arguments needed to store the loadfunction. More...
#define	XMLPortParamVariable(classname, paramname, variable, xmlelement, mode)
	Declares an XML attribute with a name, which will be set through a variable. More...

Detailed Description

Declaration of the XMLPort helper classes and macros.

XMLPort is a virtual function of every BaseObject. Every object can change this function. The XMLPort function gets called with an XMLElement, containing all attributes and subclasses the object gets from the levelfile.

This file declares classes and macros to simplify XML-parsing.

Macro Definition Documentation

#define XMLPortObject	(		classname,
			objectclass,
			sectionname,
			loadfunction,
			savefunction,
			xmlelement,
			mode
	)

Value:

static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
    static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##saveexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::savefunction), std::string( #classname ) + "::" + #savefunction); \
    XMLPortObjectGeneric(xmlcontainer##loadfunction##savefunction, classname, objectclass, sectionname, xmlcontainer##loadfunction##savefunction##loadexecutor, xmlcontainer##loadfunction##savefunction##saveexecutor, xmlelement, mode, false, true)

This is the same as XMLPortObjectExtended, but bApplyLoaderMask is false and bLoadBefore is true by default.

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

Value:

static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
    static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##saveexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::savefunction), std::string( #classname ) + "::" + #savefunction); \
    XMLPortObjectGeneric(xmlcontainer##loadfunction##savefunction, classname, objectclass, sectionname, xmlcontainer##loadfunction##savefunction##loadexecutor, xmlcontainer##loadfunction##savefunction##saveexecutor, xmlelement, mode, bApplyLoaderMask, bLoadBefore)

Declares a possible sub-object that can be added in the XML file.

Parameters

classname	The name of the class that uses this macro
objectclass	The baseclass of objects that can be added
sectionname	The name of the subsection in the XML file that encloses the sub-objects ("" means no subsection)
loadfunction	The function to add a new object to the class
savefunction	The function to get all added objects from the class
xmlelement	The XMLElement (received through the XMLPort function)
mode	The mode (load/save) (received through the XMLPort function)
bApplyLoaderMask	If this is true, an added sub-object gets loaded only if it's class is included in the Loaders ClassTreeMask (this is usually false)
bLoadBefore	If this is true, the sub-object gets loaded (through XMLPort) BEFORE it gets added to the main class (this is usually true)

bApplyLoaderMask is usually false for the following reason: If the loaders mask says, for example, "load only SpaceShips" and you added weapons to the SpaceShips, then the Weapons will still be loaded (which is most probably what you want). Of course, if there are "standalone" weapons in the level, they wont be loaded.

If bLoadBefore is true, an added object already has all attributes set (like it's name). This is most likely the best option, so this is usually true.

The load- and savefunctions have to follow an exactly defined protocol. Loadfunction: The loadfunction gets a pointer to the object.

void loadfunction(objectclass* pointer);

Savefunction: The savefunction gets an index, starting with 0. For every returnvalue != 0, the savefunction gets called again, but with index + 1. It's the functions responsibility to do something smart with the index and to return 0 if all objects were returned.

objectclass* savefunction(unsigned int index) const;

Possible implementation:

objectclass* savefunction(unsigned int index) const
{
  if (index < number_of_added_objects_)
    return my_added_objects[index];
  else
    return nullptr;
}

Example: Possible usage of the macro:

XMLPortObject(SpaceShip, Weapon, "weapons", addWeapon, getWeapon, xmlelement, mode, false, true);

Now you can add weapons through the XML file:

<SpaceShip someattribute="..." ...>
  <weapons>
    <Weapon someattribute="..." ... />
    <Weapon someattribute="..." ... />
    <Weapon someattribute="..." ... />
  </weapons>
</SpaceShip>

Note that "weapons" is the subsection. This allows you to add more types of sub-objects. In our example, you could add pilots, blinking lights or other stuff. If you don't want a subsection, just use "" (an empty string). Then you can add sub-objects directly into the mainclass.

#define XMLPortObjectExtendedTemplate	(		classname,
			objectclass,
			sectionname,
			loadfunction,
			savefunction,
			xmlelement,
			mode,
			bApplyLoaderMask,
			bLoadBefore,
			...
	)

Value:

static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor<void, classname, __VA_ARGS__ >(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
    static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##saveexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::savefunction), std::string( #classname ) + "::" + #savefunction); \
    XMLPortObjectGeneric(xmlcontainer##loadfunction##savefunction, classname, objectclass, sectionname, xmlcontainer##loadfunction##savefunction##loadexecutor, xmlcontainer##loadfunction##savefunction##saveexecutor, xmlelement, mode, bApplyLoaderMask, bLoadBefore)

This is the same as XMLPortObjectExtended, but you can specify the loadfunction by adding the param types.

See XMLPortParamTemplate for more details about the types.

#define XMLPortObjectGeneric	(		containername,
			classname,
			objectclass,
			sectionname,
			loadexecutor,
			saveexecutor,
			xmlelement,
			mode,
			bApplyLoaderMask,
			bLoadBefore
	)

Value:

orxonox::XMLPortClassObjectContainer<classname, objectclass>* containername = (orxonox::XMLPortClassObjectContainer<classname, objectclass>*)(ClassIdentifier<classname>::getIdentifier()->getXMLPortObjectContainer(sectionname)); \
    if (!containername) \
    { \
        containername = new orxonox::XMLPortClassObjectContainer<classname, objectclass>(std::string(sectionname), ClassIdentifier<classname>::getIdentifier(), loadexecutor, saveexecutor, bApplyLoaderMask, bLoadBefore); \
        ClassIdentifier<classname>::getIdentifier()->addXMLPortObjectContainer(sectionname, containername); \
    } \
    containername->port(this, xmlelement, mode)

Generic XMLPortObject macro, that gets called by all other XMLPortObject macros above.

#define XMLPortObjectTemplate	(		classname,
			objectclass,
			sectionname,
			loadfunction,
			savefunction,
			xmlelement,
			mode,
			...
	)

Value:

static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor<void, classname, __VA_ARGS__ >(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
    static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##saveexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::savefunction), std::string( #classname ) + "::" + #savefunction); \
    XMLPortObjectGeneric(xmlcontainer##loadfunction##savefunction, classname, objectclass, sectionname, xmlcontainer##loadfunction##savefunction##loadexecutor, xmlcontainer##loadfunction##savefunction##saveexecutor, xmlelement, mode, false, true)

This is the same as XMLPortObject, but you can specify the loadfunction by adding the param types.

See XMLPortParamTemplate for more details about the types.

#define XMLPortParam	(		classname,
			paramname,
			loadfunction,
			savefunction,
			xmlelement,
			mode
	)

Value:

static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
    static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##saveexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::savefunction), std::string( #classname ) + "::" + #savefunction); \
    XMLPortParamGeneric(xmlcontainer##loadfunction##savefunction, classname, classname, this, paramname, xmlcontainer##loadfunction##savefunction##loadexecutor, xmlcontainer##loadfunction##savefunction##saveexecutor, xmlelement, mode)

Declares an XML attribute with a name, which will be set through load- and savefunctions.

Parameters

classname	The name of the class owning this param
paramname	The name of the attribute
loadfunction	A function to set the param in the object with a given value (~a set-function)
savefunction	A function to get the value of the param from the object (~a get-function)
xmlelement	The XMLElement, you get this from the XMLPort function
mode	The mode (load or save), you get this from the XMLPort function

In the XML file, a param or attribute will be set like this:

<classname paramname="value" />

The macro will then call loadfunction(value) to set the given value (or call savefunction() to write an existing value to an XML file).

#define XMLPortParamExtern	(		classname,
			externclass,
			object,
			paramname,
			loadfunction,
			savefunction,
			xmlelement,
			mode
	)

Value:

static ExecutorMemberPtr<externclass> xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor(&externclass::loadfunction), std::string( #externclass ) + "::" + #loadfunction); \
    static ExecutorMemberPtr<externclass> xmlcontainer##loadfunction##savefunction##saveexecutor = orxonox::createExecutor(orxonox::createFunctor(&externclass::savefunction), std::string( #externclass ) + "::" + #savefunction); \
    XMLPortParamGeneric(xmlcontainer##loadfunction##savefunction, classname, externclass, object, paramname, xmlcontainer##loadfunction##savefunction##loadexecutor, xmlcontainer##loadfunction##savefunction##saveexecutor, xmlelement, mode);

This is the same as XMLPortParam, but for attributes in an extern class.

Parameters

classname	The name of the class owning the object owning the attribute
externclass	The name of the extern class (the objects class)
object	The name of the object of the extern class (a member of the main class)
paramname	The name of the attribute
loadfunction	The function to set the attribute inside of the member object.
savefunction	The function to get the attribute from the member object
xmlelement	The XML-element that is parsed by this macro
mode	Loading or saving

Sometimes you'll have a member object in your class, which has it's own load- and savefunctions. With this macro, you can simply use them instead of writing your own functions.

Example: Your class is called SpaceShip and this class has an object (myPilot_) of class Pilot. Pilot has a name and two functions, setName(name) and getName(). Now you want an attribute "pilotname" in your SpaceShip class. Instead of writing wrapper functions, you can simply use the XMLPortParamExtern macro:

XMLPortParamExtern(SpaceShip, Pilot, myPilot_, "pilotname", setName, getName, xmlelement, mode);

#define XMLPortParamExternTemplate	(		classname,
			externclass,
			object,
			paramname,
			loadfunction,
			savefunction,
			xmlelement,
			mode,
			...
	)

Value:

static ExecutorMemberPtr<externclass> xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor<void, externclass, __VA_ARGS__ >(&externclass::loadfunction), std::string( #externclass ) + "::" + #loadfunction); \
    static ExecutorMemberPtr<externclass> xmlcontainer##loadfunction##savefunction##saveexecutor = orxonox::createExecutor(orxonox::createFunctor(&externclass::savefunction), std::string( #externclass ) + "::" + #savefunction); \
    XMLPortParamGeneric(xmlcontainer##loadfunction##savefunction, classname, externclass, object, paramname, xmlcontainer##loadfunction##savefunction##loadexecutor, xmlcontainer##loadfunction##savefunction##saveexecutor, xmlelement, mode);

This is the same as XMLPortParamTemplate, but for extern attributes (see XMLPortParamExtern).

#define XMLPortParamGeneric	(		containername,
			classname,
			objectclass,
			object,
			paramname,
			loadexecutor,
			saveexecutor,
			xmlelement,
			mode
	)

Value:

orxonox::XMLPortClassParamContainer<objectclass>* containername = static_cast<orxonox::XMLPortClassParamContainer<objectclass>*>(ClassIdentifier<classname>::getIdentifier()->getXMLPortParamContainer(paramname)); \
    if (!containername) \
    { \
        containername = new orxonox::XMLPortClassParamContainer<objectclass>(std::string(paramname), ClassIdentifier<classname>::getIdentifier(), loadexecutor, saveexecutor); \
        ClassIdentifier<classname>::getIdentifier()->addXMLPortParamContainer(paramname, containername); \
    } \
    containername->port(orxonox_cast<BaseObject*>(this), object, xmlelement, mode)

This is the generic XMLPort param macro, which is used by all six specialized macros above.

#define XMLPortParamLoadOnly	(		classname,
			paramname,
			loadfunction,
			xmlelement,
			mode
	)

Value:

static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##0##loadexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
    XMLPortParamGeneric(xmlcontainer##loadfunction##0, classname, classname, this, paramname, xmlcontainer##loadfunction##0##loadexecutor, 0, xmlelement, mode)

Declares an XML attribute with a name, which can be set through a loadfunction.

This is the same as XMLPortParam, but you don't need a savefunction (get-function). Therefore, this param won't be saved in an XML file, but you can add the attribute manually an it will be loaded.

This might be helpful in cases, when you have several options to set a value, for example the rotation. You can set the rotation with a quaternion, but you could also use three angles. When saving the object, only one of both options has to be saved; this is, where this macro helps.

#define XMLPortParamLoadOnlyTemplate	(		classname,
			paramname,
			loadfunction,
			xmlelement,
			mode,
			...
	)

Value:

static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##0##loadexecutor = orxonox::createExecutor(orxonox::createFunctor<void, classname, __VA_ARGS__ >(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
    XMLPortParamGeneric(xmlcontainer##loadfunction##0, classname, classname, this, paramname, xmlcontainer##loadfunction##0##loadexecutor, 0, xmlelement, mode)

This is the same as XMLPortParamTemplate, but for load-only attributes (see XMLPortParamLoadOnly).

#define XMLPortParamTemplate	(		classname,
			paramname,
			loadfunction,
			savefunction,
			xmlelement,
			mode,
			...
	)

Value:

static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor<void, classname, __VA_ARGS__ >(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
    static ExecutorMemberPtr<classname> xmlcontainer##loadfunction##savefunction##saveexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::savefunction), std::string( #classname ) + "::" + #savefunction); \
    XMLPortParamGeneric(xmlcontainer##loadfunction##savefunction, classname, classname, this, paramname, xmlcontainer##loadfunction##savefunction##loadexecutor, xmlcontainer##loadfunction##savefunction##saveexecutor, xmlelement, mode)

This is the same as XMLPortParam, but you can set the template arguments needed to store the loadfunction.

Sometimes the name of the loadfunction is ambiguous (example: setPosition(Vector3) or setPosition(float, float, float)). In this case, you can choose the right function by telling the types of the functionparams. In our example, this would be either

XMLPortParamTemplate(classname, paramname, loadfunction, savefunction, xmlelement, mode, Vector3);

or

XMLPortParamTemplate(classname, paramname, loadfunction, savefunction, xmlelement, mode, float, float, float);

You don't have to use this, if there exist only one function with the given name.

#define XMLPortParamVariable	(		classname,
			paramname,
			variable,
			xmlelement,
			mode
	)

Value:

XMLPortVariableHelperClass xmlcontainer##variable##dummy(static_cast<void*>(&variable)); \
    static ExecutorMemberPtr<orxonox::XMLPortVariableHelperClass> xmlcontainer##variable##loadexecutor = orxonox::createExecutor(orxonox::createFunctor(orxonox::XMLPortVariableHelperClass::getLoader(variable)), std::string( #classname ) + "::" + #variable + "loader"); \
    static ExecutorMemberPtr<orxonox::XMLPortVariableHelperClass> xmlcontainer##variable##saveexecutor = orxonox::createExecutor(orxonox::createFunctor(orxonox::XMLPortVariableHelperClass::getSaver (variable)), std::string( #classname ) + "::" + #variable + "saver" ); \
    XMLPortParamGeneric(xmlcontainer##variable, classname, orxonox::XMLPortVariableHelperClass, &xmlcontainer##variable##dummy, paramname, xmlcontainer##variable##loadexecutor, xmlcontainer##variable##saveexecutor, xmlelement, mode)

Declares an XML attribute with a name, which will be set through a variable.

Parameters

classname	The name of the class owning this param
paramname	The name of the attribute
variable	Name of the variable used to save and load the value
xmlelement	The XMLElement, you get this from the XMLPort function
mode	The mode (load or save), you get this from the XMLPort function

In the XML file, a param or attribute will be set like this:

<classname paramname="value" />

The macro will then store "value" in the variable or read it when saving.