public class GoXmlBindingTransformer : GoXmlTransformer, IGoXmlTransformer
public class GoXmlBindingTransformer : GoXmlTransformer, IGoXmlTransformer
Use this kind of transformer when you have complete control over the XML schema that you want to read and write and can follow the conventions established by this class.
The following two transformers are similar to the SimpleXmlTransformBasicNode and SimpleXmlTransformLink transformer subclasses defined in the remarks for the GoXmlTransformer documentation. For each GoXmlBindingTransformer you need to specify an element name, create a prototype object, and add bindings between attribute names and property names.
// create a prototype node that is copied when consuming a "node" element GoBasicNode bn = new GoBasicNode(); bn.LabelSpot = GoObject.Middle; bn.Text = ""; // ElementName is "node"; Prototype is this GoBasicNode GoXmlBindingTransformer bt1 = new GoXmlBindingTransformer("node", bn); // generates attributes for all named ports, for GoBasicNode just "Port", // to define their id's without generating separate elements for the ports bt1.HandlesNamedPorts = true; // read/write three attributes for each node, each attribute's value given by a property // note that the property can be a "path" of property names separated by periods, // when the desired value is not an immediate property on the object (the GoBasicNode in this case) bt1.AddBinding("label", "Text"); bt1.AddBinding("color", "Shape.BrushColor"); // typically the Location property is last, in case any of the previous // properties cause a change in node size and thus in the node's Location bt1.AddBinding("loc", "Location"); // register this transformer for GoBasicNodes and the element name "node" readerorwriter.AddTransformer(bt1); // create a prototype link GoLabeledLink ll = new GoLabeledLink(); GoText lab = new GoText(); lab.Selectable = false; ll.MidLabel = lab; // ElementName is "link"; Prototype is this GoLabeledLink GoXmlBindingTransformer bt2 = new GoXmlBindingTransformer("link", ll); // read/write three attributes for each link, including the two ports and the MidLabel's string bt2.AddBinding("from", "FromPort"); bt2.AddBinding("to", "ToPort"); bt2.AddBinding("label", "MidLabel.Text"); // register this transformer for GoLabeledLinks and the element name "link" readerorwriter.AddTransformer(bt2);
These two transformers produce an XML document such as: <graph> <node Port="0" label="Linen" color="-331546" loc="112 195" /> <node Port="1" label="DarkKhaki" color="-4343957" loc="221 155" /> <node Port="2" label="LightSteelBlue" color="-5192482" loc="237 221" /> <node Port="3" label="DeepSkyBlue" color="-16728065" loc="146 288" /> <link from="0" to="1" label="zeroone" /> <link from="1" to="2" label="onetwo" /> <link from="2" to="3" label="twothree" /> <link from="0" to="3" label="zerothree" /> </graph> Note that the ports get unique identifiers, not the nodes, because HandlesNamedPorts is true. If you also want the nodes to get unique identifiers, you can set GoXmlTransformer.IdAttributeUsedForSharedObjects to true. Neither identifier is at all related to an Northwoods.Go.IGoIdentifiablePart.Northwoods.Go.IGoIdentifiablePart.PartID.
As special cases, there are two property names that provide special behavior. For the Northwoods.Go.GoStroke, Northwoods.Go.GoLabeledLink, Northwoods.Go.GoPolygon, and Northwoods.Go.GoDrawing classes, you can bind to the "Points" property in order to get or set the array of points used to define those shapes. The "Points" property is not treated specially for objects of any other type.
Also as a special case for node classes, the "TreeParentNode" property binding is handled as a reference to another node, where the other node is considered to be the "parent" node in a tree-structured diagram. This supports the definition of XML that only has elements for nodes, with an implicit link from a "parent" node to the node whose element includes the attribute corresponding to the "TreeParentNode" property. The TreeLinkPrototype property of this transformer provides a link that is copied when consuming such an element. The "TreeParentNode" property is not treated specially for objects that are not instances of IGoNode.
If you define a property binding using the special "TreeParentNode" property name, TreeStructured should not be true, because TreeStructured denotes nested XML elements, not the use of an attribute that refers to a node. It also does not make sense to have more than one attribute/property binding using the special "TreeParentNode" property name.
// create a prototype node that is copied when consuming a "node" element GoBasicNode bn = new GoBasicNode(); bn.LabelSpot = GoObject.Middle; bn.Text = ""; // ElementName is "node"; Prototype is this GoBasicNode GoXmlBindingTransformer bt1 = new GoXmlBindingTransformer("node", bn); // all nodes get an "id" attribute bt1.IdAttributeUsedForSharedObjects = true; // read/write three attributes for each node, each attribute's value given by a property // note that the property can be a "path" of property names separated by periods, // when the desired value is not an immediate property on the object (the GoBasicNode in this case) bt1.AddBinding("label", "Text"); bt1.AddBinding("color", "Shape.BrushColor"); // typically the Location property is last, in case any of the previous // properties cause a change in node size and thus in the node's Location bt1.AddBinding("loc", "Location"); // use the special "TreeParentNode" pseudo-property to indicate that the "parent" // attribute should be a reference to the node's parent node, if any bt1.AddBinding("parent", "TreeParentNode"); // create a prototype link to connect a parent node to this transformer's node GoLink ll = new GoLink(); ll.ToArrow = true; ll.Pen = new Pen(Color.Blue, 2); bt1.TreeLinkPrototype = ll; // register this transformer for GoBasicNodes and the element name "node" readerorwriter.AddTransformer(bt1);
This single transformer for GoBasicNode produces an XML document such as: <graph> <node id="0" label="Crimson" color="-2354116" loc="102 196" /> <node id="1" label="DarkCyan" color="-16741493" loc="210 157" parent="0" /> <node id="2" label="PaleGoldenrod" color="-1120086" loc="226 219" parent="0" /> <node id="3" label="Silver" color="-4144960" loc="343 254" parent="2" /> <node id="4" label="Purple" color="-8388480" loc="344 189" parent="2" /> </graph> Note that the nodes have identifiers, not the ports. These identifiers are not at all related to an Northwoods.Go.IGoIdentifiablePart.Northwoods.Go.IGoIdentifiablePart.PartID. You can control which ports are used at each node in a tree diagram by setting the TreeParentNodePortPath and TreeChildNodePortPath properties of the transformer. You can also control whether links go from the parent node to the child node, or vice-versa, by setting the TreeLinksToChildren property.
GoXmlWriter and GoXmlReader also make special provision for a root that is a Northwoods.Go.GoDocument whose Type is associated with a GoXmlBindingTransformer. When writing, the GoXmlTransformer.ElementName is used as the GoXmlWriter.RootElementName. When reading, if there is no GoXmlReader.RootObject, the Prototype is copied to be the GoXmlReader.RootObject. This makes it easy to bind Northwoods.Go.GoDocument properties with XML root attributes. However most of the other properties of transformers, such as TreeStructured or the other tree-related properties, are ignored when applied to the root object.
Bindings are inherited from transformers in the same manner that their corresponding Types inherit properties. So if you define a transformer for a Type C with a binding for the CProp property, and if you define a transformer for the Type D that inherits from C, the elements generated or consumed for instances of Type D will automatically include an attribute for the CProp property.
The binding mechanism uses reflection, so your application will need permission to use reflection. Using reflection is also slower than the equivalent functionality implemented as regular code that you implement in overrides of GoXmlTransformer.GenerateAttributes and GoXmlTransformer.ConsumeAttributes.