DomNodes and DOM Metadata Classes

Table of Contents DomNode Class Creating DomNodes DomNode Children DomNode Methods DomNode Events DomNodeDebugger Class DomNodeType and Other Metadata Classes DomNodeType Class DomNodeType.BaseOfAllTypes Other Metadata Classes Topics in this section

The fundamental DomNode class represents an individual tree node containing application data, and related classes like DomNodeType describe node metadata.

Note that all application data is contained in DomNodes. This means that much of the application's data handling can be done by working with DomNodes.

DomNodeType represents the type associated with a DomNode, and every DomNode has a DomNodeType associated with it.

The DomNode and DomNodeType classes provide basic functionality for managing the tree and nodes within that tree, including event management, unique node naming, reference tracking, transactions, and synchronization with underlying documents that store application data persistently. DomNodeType serves as a repository of information about the node type, such as palette or property information associated with it.

DomNode Class

Each DomNode object represents one node in a tree, one piece of data. The term node is also used for a DomNode.

Creating DomNodes

Because a DomNode represents application data, you can create new application data by creating a DomNode. In its constructor, you specify a DomNode's type as a DomNodeType object. For more information, see DomNodeType Class.

You can use a DomXmlReader object to create a tree of DomNodes with the appropriate types from XML data, so your application doesn't need to construct all the DomNodes itself. For details on writing and reading DomNodes to and from storage, see DOM Persistence.

DomNode Children

A child of a DomNode can be a single DomNode or a list of DomNodes, that is, IList<DomNode>, and a DomNode can have multiple children of both kinds. Each child DomNode is described by a ChildInfo object, which is metadata about a child of a DomNode, such as its name and DomNodeType. For more information on ChildInfo, see DomNodeType and Other Metadata Classes.

ChildInfo has the attribute IsList indicating whether that child is in a list or not. Children that are in a list and that have the same ChildInfo are all in the same list that is a child of the DomNode. Thus, if a child that is a list of DomNodes with a given ChildInfo already exists, you add a new node with that kind of ChildInfo to that list, just as for any collection.

DomNode Methods

Because DomNodes are tree nodes, the DomNode class has properties and methods to allow you to manipulate a tree, such as these:

• DomNode Parent: Get the parent DomNode, or null if the node is a root.
• DomNode GetRoot(): Get the root DomNode of this DomNode's subtree.
• IEnumerable<DomNode> Children: Get an enumeration of this node's children.
• SetChild(ChildInfo childInfo, DomNode child): Set the child corresponding to the child metadata ChildInfo when the child is not in a list.
• DomNode GetChild(ChildInfo childInfo): Get the child corresponding to the given child metadata ChildInfo when the child is not in a list.
• RemoveFromParent(): Remove the DomNode from its parent. The DomNode as a child of its parent can be in a list or not.
• DomNode GetLowestCommonAncestor(DomNode node1, DomNode node2): Get the lowest common ancestor (LCA) of a pair of DOM nodes. The LCA is the common ancestor of the two nodes that is furthest from the root node.
• Copy(): Several methods with different parameters to make deep copies of DomNode trees.

As application data changes, you can modify DomNodes to keep in sync with the changes. For example, if new data is added, you can add DomNodes at appropriate places in the tree.

DomNode Events

DomNode also defines a set of events indicating tree changes. These events are raised if the DomNode or any DomNode of its subtree changes:

• AttributeChanging: Raised before an attribute is changed to a new value.
• AttributeChanged: Raised after an attribute is changed to a new value.
• ChildInserting: Raised before a child is inserted into a child list or added as a child to a node.
• ChildInserted: Raised after a child is inserted into a child list or added as a child to a node.
• ChildRemoving: Raised before a child is removed from a child list or removed as a child from a node.
• ChildRemoved: Raised after a child is removed from a child list or removed as a child from a node.

These events use the AttributeEventArgs and ChildEventArgs classes to provide event information.

Note that if the root DomNode subscribes to any of these events, the event occurs if any DomNode changes.

DomNodeDebugger Class

DomNodeDebugger is a private subclass of DomNode devoted to helping debug the DOM. For a full description of how this class aids debugging DOM code, see Debugging the DOM with Visual Studio. For DOM debugging topics, see DOM Debugging.

DomNodeType and Other Metadata Classes

These metadata classes contain the information provided in the type definition, as well as other information.

DomNodeType Class

A DomNodeType object specifies the type of a DomNode and holds all the information about the type. A DomNodeType can contain attributes, child node types (types of children of a node of this type), and DOM adapters. A DomNodeType is constructed from the name of the type:

DomNodeType(string name)

DomNodeType derives from NamedMetadata, which is the general class for type metadata. NamedMetadata has a very useful method:

SetTag(object key, object value)

You can use SetTag() to add any kind of metadata to a DomNodeType object, such as palette information. For examples, see Using DOM Metadata for Palettes and Other Items and Specifying Property Descriptors in Constructors.

Use the DomNodeType.Define() method to define DOM adapters for the types to which they apply. For details on how to do this, see Defining DOM Adapters for Types.

DomNodeType.BaseOfAllTypes

DomNodeType.BaseOfAllTypes is the node type from which all node types ultimately derive. This type is useful to define general-purpose DOM adapters that apply to all types of DomNodes.

In particular, DomNodeType.BaseOfAllTypes is used to enable metadata driven property editing for the DOM. For more details, see Metadata Driven Property Editing.

Other Metadata Classes

The general class of metadata, FieldMetadata, describes the fields inside a DomNodeType. These classes all derive from FieldMetadata:

• AttributeInfo: Metadata about a DomNodeType's attributes, which include the attribute type AttributeType, any restrictions the attribute was defined with, such as its maximum value, and any additional restriction rules defined. AttributeType describes a DomNode attribute's type, which can be a primitive value or an array of primitive values.
• ChildInfo: Metadata about a child of a DomNode. Child information includes an identifying name, the child's DomNodeType and whether the child is a list of nodes, as mentioned in DomNode Children. ChildInfo contains any restriction rules, such as limits on the number of children. ChildInfo can serve as an identifier for the type of a node's child. Typically, every DomNode has a ChildInfo associated with it, even the type of the root DomNode. In fact, the root DomNode must have an associated ChildInfo for the application data persistence mechanism of ATF to work.
• ExtensionInfo: A DOM extension defined for this type, which is nearly always a DOM adapter. For information on what DOM adapters can do, see DOM Adapters.

Topics in this section