Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changes between Initial Version and Version 1 of code/doc/XMLPort


Ignore:
Timestamp:
Oct 1, 2008, 4:16:34 AM (16 years ago)
Author:
landauf
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • code/doc/XMLPort

    v1 v1  
     1= XMLPort =
     2[[TracNav(TracNav/TOC_Development)]]
     3[[TOC]]
     4
     5== Description ==
     6XMLPort.h is a compilation of macros and classes for easy XML parsing. Every object starting with [wiki:BaseObject] has some attributes to be set, either by a default value or specified in the [wiki:Level XML level file]. The [wiki:Loader] parses the file, creates the main objects an passes the attributes and subobjects to their XMLPort function.
     7
     8Inside of this function, one macro for every parameter and every possible subobject defines how to assign the loaded values to the newly created object.
     9
     10== The XMLPort Function ==
     11This is how an empty XMLPort function looks like:
     12
     13*.h file:
     14{{{
     15class SomeClass : public BaseClass
     16{
     17    public:
     18        virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
     19};
     20}}}
     21
     22*.cc file:
     23{{{
     24void SomeClass::XMLPort(Element& xmlelement, XMLPort::Mode mode)
     25{
     26    SUPER(SomeClass, XMLPort, xmlelement, mode);
     27}
     28}}}
     29
     30''xmlelement'' is a container, containing all attributes and subobjects passed to this class.[[br]]
     31''mode'' says if we're loading new objects from a file or saving existing objects to a file.[[br]]
     32''SUPER'' is a macro, see [wiki:Super] for more information.
     33
     34'''Important''': XMLPort is a '''virtual''' function.
     35
     36== Parameters ==
     37=== General ===
     38To load parameters like the name of an object, you need three things:
     39
     401. A set-function in your class to set the parameter:
     41{{{
     42    void setName(const std::string& name);
     43}}}
     44
     452. A get-function returning the parameter:
     46{{{
     47    const std::string& getName() const;
     48}}}
     49
     503. A call to the XMLPortParam macro in XMLPort:
     51{{{
     52void SomeClass::XMLPort(Element& xmlelement, XMLPort::Mode mode)
     53{
     54    SUPER(SomeClass, XMLPort, xmlelement, mode);
     55
     56    XMLPortParam(SomeClass, "name", setName, getName, xmlelement, mode);
     57}
     58}}}
     59
     60To create an instance of ''SomeClass'' and set the parameter ''name'', write the following text into the XML file:
     61{{{
     62<SomeClass name="funny_name" />
     63}}}
     64
     65
     66XMLPortParam has the following form:
     67 * '''XMLPortParam('''''classname, "param-name", set-function, get-function, xmlelement, mode''''')'''
     68''xmlelement'' and ''mode'' are received by the XMLPort function.
     69
     70=== Ambiguity ===
     71Sometimes the name of the set-function in XMLPortParam is ambiguous, because the function is overloaded.
     72
     73Example:
     74{{{
     75    void setPosition(float x, float y, float z);
     76    void setPosition(const Vector3& position);
     77}}}
     78
     79In this case, the following code will fail:
     80{{{
     81XMLPortParam(SomeClass, "position", setPosition, getPosition, xmlelement, mode);
     82// Error: setPosition is ambiguous
     83}}}
     84
     85The problem can be solved by using XMLPortParamTemplate:
     86{{{
     87// If you want to use the first variant with three floats:
     88XMLPortParamTemplate(SomeClass, "position", setPosition, getPosition, xmlelement, mode, float, float, float);
     89
     90// If you want to use the second variant with a Vector3:
     91XMLPortParamTemplate(SomeClass, "position", setPosition, getPosition, xmlelement, mode, const Vector3&);
     92
     93}}}
     94
     95As you can see, the type(s) of the function arguments are just appended at the end of the macro.
     96
     97=== Loadonly ===
     98In 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.
     99
     100Example: 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":
     101
     102{{{
     103XMLPortParamLoadOnly(SomeClass, "three-angles", setAngles, xmlelement, mode);
     104}}}
     105As you can see, there's no get-function.
     106
     107Note: There is also a related macro called XMLPortParamLoadOnlyTemplate used to avoid ambiguity.
     108
     109=== Extern parameters ===
     110Sometimes you have a memberobject in you class which has a parameter that you want to set through XMLPort in your own class.
     111
     112Example:
     113{{{
     114class Position
     115{
     116    public:
     117        void setPosition(const Vector3& position);
     118        const Vector3& getPosition() const;
     119
     120    private:
     121        Vector3 position_;
     122};
     123
     124class SomeClass
     125{
     126    public:
     127        virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
     128
     129    private:
     130        Position position_;
     131}
     132}}}
     133
     134Of 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''':
     135{{{
     136XMLPortParamExtern(SomeClass, Position, this->position_, "position", setPosition, getPosition, \
     137                                                                             xmlelement, mode);
     138}}}
     139
     140Note: 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.
     141
     142Note: There is also a related macro called XMLPortParamExternTemplate used to avoid ambiguity.
     143
     144== Objects ==