Changes between Version 2 and Version 3 of code/doc/XMLPort

Timestamp:

Oct 1, 2008, 4:41:09 AM (16 years ago)

Author:

landauf

Comment:

—

code/doc/XMLPort

@@ -143 +143 @@
 
 == 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.[[br]]
+''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.[[br]]
+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 [wiki:XMLPort#Ambiguity 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 [wiki: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 [wiki:XMLPort#Ambiguity the chapter above]).