Orxonox: src/core/XMLPort.h File Reference

# 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/Debug.h"`
`#include "util/Exception.h"`
`#include "util/MultiType.h"`
`#include "util/OrxAssert.h"`
`#include "Factory.h"`
`#include "Identifier.h"`
`#include "Executor.h"`
`#include "BaseObject.h"`

## Namespaces

namespace | orxonox

## 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...

## Defines

#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.
#define | XMLPortObjectExtended(classname, objectclass, sectionname, loadfunction, savefunction, xmlelement, mode, bApplyLoaderMask, bLoadBefore)
#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. See XMLPortParamTemplate for more details about the types.
#define | XMLPortObjectGeneric(containername, classname, objectclass, sectionname, loadexecutor, saveexecutor, xmlelement, mode, bApplyLoaderMask, bLoadBefore)
| Generic XMLPortObject macro, that gets called by all other XMLPortObject macros above.
#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. See XMLPortParamTemplate for more details about the types.
#define | XMLPortParam(classname, paramname, loadfunction, savefunction, xmlelement, mode)
| Declares an XML attribute with a name, which will be set through load- and savefunctions.
#define | XMLPortParamExtern(classname, externclass, object, paramname, loadfunction, savefunction, xmlelement, mode)
#define | XMLPortParamExternTemplate(classname, externclass, object, paramname, loadfunction, savefunction, 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)
| This is the generic XMLPort param macro, which is used by all six specialized macros above.
#define | XMLPortParamLoadOnly(classname, paramname, loadfunction, xmlelement, mode)
| Declares an XML attribute with a name, which can be set through a loadfunction.
#define | XMLPortParamLoadOnlyTemplate(classname, paramname, loadfunction, xmlelement, mode,...)
| This is the same as XMLPortParamTemplate, but for load-only attributes (see XMLPortParamLoadOnly).
#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.
#define | XMLPortParamVariable(classname, paramname, variable, xmlelement, mode)
| Declares an XML attribute with a name, which will be set through a variable.

## 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.

## Define Documentation

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

Value:

    static ExecutorMember<classname>* xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
        static ExecutorMember<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.

Referenced by orxonox::OverlayGroup::XMLPort(), orxonox::HUDBar::XMLPort(), orxonox::WorldEntity::XMLPort(), orxonox::Trigger::XMLPort(), orxonox::Pawn::XMLPort(), orxonox::ControllableEntity::XMLPort(), orxonox::Attacher::XMLPort(), orxonox::WeaponPack::XMLPort(), orxonox::Weapon::XMLPort(), orxonox::QuestItem::XMLPort(), orxonox::QuestEffectBeacon::XMLPort(), orxonox::Quest::XMLPort(), orxonox::GlobalQuest::XMLPort(), orxonox::AddReward::XMLPort(), orxonox::MultiStateEngine::XMLPort(), orxonox::EventDispatcher::XMLPort(), orxonox::WaypointController::XMLPort(), and orxonox::CompoundCollisionShape::XMLPort().

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

Value:

    static ExecutorMember<classname>* xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
        static ExecutorMember<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)

Referenced by orxonox::WeaponPack::XMLPort(), orxonox::Scene::XMLPort(), orxonox::Level::XMLPort(), and orxonox::Namespace::XMLPort().

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

Value:

    static ExecutorMember<classname>* xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor<classname, __VA_ARGS__ >(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
        static ExecutorMember<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 ExecutorMember<classname>* xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor<classname, __VA_ARGS__ >(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
        static ExecutorMember<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.

Referenced by orxonox::BaseObject::XMLPort().

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

Value:

    static ExecutorMember<classname>* xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
        static ExecutorMember<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).

Referenced by orxonox::OverlayText::XMLPort(), orxonox::OverlayGroup::XMLPort(), orxonox::OrxonoxOverlay::XMLPort(), orxonox::NotificationQueue::XMLPort(), orxonox::UnderAttackHealthBar::XMLPort(), orxonox::TeamBaseMatchScore::XMLPort(), orxonox::PongScore::XMLPort(), orxonox::HUDRadar::XMLPort(), orxonox::HUDNavigation::XMLPort(), orxonox::HUDHealthBar::XMLPort(), orxonox::HUDBar::XMLPort(), orxonox::BarColour::XMLPort(), orxonox::GUIOverlay::XMLPort(), orxonox::FadeoutText::XMLPort(), orxonox::WorldEntity::XMLPort(), orxonox::Trigger::XMLPort(), orxonox::DistanceTrigger::XMLPort(), orxonox::CheckPoint::XMLPort(), orxonox::TeamSpawnPoint::XMLPort(), orxonox::SpawnPoint::XMLPort(), orxonox::PongCenterpoint::XMLPort(), orxonox::Planet::XMLPort(), orxonox::SpaceShip::XMLPort(), orxonox::Pawn::XMLPort(), orxonox::ParticleSpawner::XMLPort(), orxonox::ParticleEmitter::XMLPort(), orxonox::MovableEntity::XMLPort(), orxonox::Model::XMLPort(), orxonox::Light::XMLPort(), orxonox::ForceField::XMLPort(), orxonox::FadingBillboard::XMLPort(), orxonox::ControllableEntity::XMLPort(), orxonox::CameraPosition::XMLPort(), orxonox::BlinkingBillboard::XMLPort(), orxonox::Billboard::XMLPort(), orxonox::Backlight::XMLPort(), orxonox::Attacher::XMLPort(), orxonox::WeaponSet::XMLPort(), orxonox::HsW01::XMLPort(), orxonox::EnergyDrink::XMLPort(), orxonox::WeaponMode::XMLPort(), orxonox::DefaultWeaponmodeLink::XMLPort(), orxonox::Scene::XMLPort(), orxonox::QuestListener::XMLPort(), orxonox::QuestItem::XMLPort(), orxonox::QuestEffectBeacon::XMLPort(), orxonox::QuestDescription::XMLPort(), orxonox::ChangeQuestStatus::XMLPort(), orxonox::AddQuestHint::XMLPort(), orxonox::PickupSpawner::XMLPort(), orxonox::ModifierPickup::XMLPort(), orxonox::Jump::XMLPort(), orxonox::HealthUsable::XMLPort(), orxonox::HealthImmediate::XMLPort(), orxonox::BaseItem::XMLPort(), orxonox::Level::XMLPort(), orxonox::Engine::XMLPort(), orxonox::EventListener::XMLPort(), orxonox::WaypointPatrolController::XMLPort(), orxonox::WaypointController::XMLPort(), orxonox::SphereCollisionShape::XMLPort(), orxonox::PlaneCollisionShape::XMLPort(), orxonox::ConeCollisionShape::XMLPort(), orxonox::BoxCollisionShape::XMLPort(), orxonox::Template::XMLPort(), orxonox::Namespace::XMLPort(), and orxonox::BaseObject::XMLPort().

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

Value:

    static ExecutorMember<externclass>* xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor(&externclass::loadfunction), std::string( #externclass ) + "::" + #loadfunction); \
        static ExecutorMember<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);

Referenced by orxonox::GlobalShader::XMLPort().

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

Value:

    static ExecutorMember<externclass>* xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor<externclass, __VA_ARGS__ >(&externclass::loadfunction), std::string( #externclass ) + "::" + #loadfunction); \
        static ExecutorMember<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(static_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 ExecutorMember<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.

Referenced by orxonox::WorldEntity::XMLPort(), orxonox::DistanceTrigger::XMLPort(), orxonox::Level::XMLPort(), orxonox::Engine::XMLPort(), orxonox::CollisionShape::XMLPort(), and orxonox::BoxCollisionShape::XMLPort().

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

Value:

    static ExecutorMember<classname>* xmlcontainer##loadfunction##0##loadexecutor = orxonox::createExecutor(orxonox::createFunctor<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 ExecutorMember<classname>* xmlcontainer##loadfunction##savefunction##loadexecutor = orxonox::createExecutor(orxonox::createFunctor<classname, __VA_ARGS__ >(&classname::loadfunction), std::string( #classname ) + "::" + #loadfunction); \
        static ExecutorMember<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.

Referenced by orxonox::WorldEntity::XMLPort(), orxonox::Trigger::XMLPort(), orxonox::MobileEntity::XMLPort(), orxonox::ModifierPickup::XMLPort(), and orxonox::CollisionShape::XMLPort().

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

Value:

    XMLPortVariableHelperClass xmlcontainer##variable##dummy(static_cast<void*>(&variable)); \
        static ExecutorMember<orxonox::XMLPortVariableHelperClass>* xmlcontainer##variable##loadexecutor = static_cast<ExecutorMember<orxonox::XMLPortVariableHelperClass>*>(orxonox::createExecutor(orxonox::createFunctor(orxonox::XMLPortVariableHelperClass::getLoader(variable)), std::string( #classname ) + "::" + #variable + "loader")); \
        static ExecutorMember<orxonox::XMLPortVariableHelperClass>* xmlcontainer##variable##saveexecutor = static_cast<ExecutorMember<orxonox::XMLPortVariableHelperClass>*>(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.

Referenced by orxonox::SpaceShip::XMLPort(), and orxonox::MobileEntity::XMLPort().