<?xml version="1.0" encoding="utf-8"?>
<interface name="DOM_Node" short="the Document Object Model (DOM) DOM_Node interface">

<comments>
	Copyright 2003 Michael B. Allen &lt;mballen@erols.com&gt;
	Generated by CStyleX 0.1.1
</comments>

<include>domc.h</include>

<title>DOM_Node</title>

<desc>
<table>
<title>Values of nodeName, nodeValue, and attributes according to node type</title>
<tr>
<th>Node Interface</th>
<th>nodeName</th>
<th>nodeValue</th>
<th>nodeType</th>
</tr>

<tr>
<td><tt>DOM_Attr</tt></td>
<td>name of attribute</td>
<td>value of attribute</td>
<td><tt>DOM_ATTRIBUTE_NODE</tt></td>
</tr>

<tr>
<td><tt>DOM_CDATASection</tt></td>
<td><code>&quot;#cdata-section&quot;</code></td>
<td>content of the CDATA Section</td>
<td><tt>DOM_CDATA_SECTION_NODE</tt></td>
</tr>

<tr>
<td><tt>DOM_Comment</tt></td>
<td><code>&quot;#comment&quot;</code></td>
<td>content of the comment</td>
<td><tt>DOM_COMMENT_NODE</tt></td>
</tr>

<tr>
<td><tt>DOM_Document</tt></td>
<td><code>&quot;#document&quot;</code></td>
<td><tt>NULL</tt></td>
<td><tt>DOM_DOCUMENT_NODE</tt></td>
</tr>

<tr>
<td><tt>DOM_DocumentFragment</tt></td>
<td><code>&quot;#document-fragment&quot;</code></td>
<td><tt>NULL</tt></td>
<td><tt>DOM_DOCUMENT_FRAGMENT_NODE</tt></td>
</tr>

<tr>
<td><tt>DOM_DocumentType</tt></td>
<td>document type name</td>
<td><tt>NULL</tt></td>
<td><tt>DOM_DOCUMENT_TYPE_NODE</tt></td>
</tr>

<tr>
<td><tt>DOM_Element</tt></td>
<td>tag name</td>
<td><tt>NULL</tt></td>
<td><tt>DOM_ELEMENT_NODE</tt></td>
</tr>

<tr>
<td><tt>DOM_Entity</tt></td>
<td>entity name</td>
<td><tt>NULL</tt></td>
<td><tt>DOM_ENTITY_NODE</tt></td>
</tr>

<tr>
<td><tt>DOM_EntityReference</tt></td>
<td>name of entity referenced</td>
<td><tt>NULL</tt></td>
<td><tt>DOM_ENTITY_REFERENCE_NODE</tt></td>
</tr>

<tr>
<td><tt>DOM_Notation</tt></td>
<td>notation name</td>
<td><tt>NULL</tt></td>
<td><tt>DOM_NOTATION_NODE</tt></td>
</tr>

<tr>
<td><tt>DOM_ProcessingInstruction</tt></td>
<td>target</td>
<td>content excluding target</td>
<td><tt>DOM_PROCESSING_INSTRUCTION_NODE</tt></td>
</tr>

<tr>
<td><tt>DOM_Text</tt></td>
<td><code>&quot;#text&quot;</code></td>
<td>content of the text node</td>
<td><tt>DOM_TEXT_NODE</tt></td>
</tr>
</table>

The <tt>DOM_Node</tt> type is the primary datatype of the Document Object Model. Most of the other DOM interfaces inherit this interface. All <tt>DOM_Nodes</tt> have <tt>nodeName</tt>, <tt>nodeValue</tt>, and <tt>nodeType</tt> members. The vaules of these members depends on the node type. For example the <tt>DOM_Element</tt> node has a <tt>nodeValue</tt> corresponding to the tag name and a <tt>NULL</tt> <tt>nodeValue</tt>.
<p/>
Only the <tt>DOM_Element</tt> node type has attributes. All other node types have a <tt>NULL</tt> <tt>attributes</tt> member.
Child nodes are accessable through the <tt>childNodes</tt> <tt>DOM_NodeList</tt> member and the <tt>firstChild</tt>, <tt>lastChild</tt>, <tt>previousSibling</tt>, and <tt>nextSibling</tt> members. Not all element types have child nodes.
<br clear="right"/>
<p/>
In DOMC node inheritance is emulated with simple <tt>typedef</tt> statements and a <tt>union</tt> that contains all possible subclass attributes. To access a child interface specific attribute it may be necessary to access it through this union. For example the <tt>systemId</tt> of a notation node is currently only accessible through the <tt>union</tt> like:
<pre>
DOM_String *sysid;
...
sysid = node-&gt;u.Notation.systemId;
</pre>
Care must be taken when modifing these union members (this is not well defined yet). Attributes accessible through the <tt>union</tt> that may need to be modified have helper methods to make this less awkward. The <tt>DOM_Node_setNodeValue</tt> function must be used to set the <tt>nodeValue</tt> member.
<table>
<title>Functions to get and set certain node members</title>
<tr><td><tt>DOM_Node_getNodeValue</tt></td><td>get <tt>nodeValue</tt> attribute</td></tr>
<tr><td><tt>DOM_Node_setNodeValue</tt></td><td>set <tt>nodeValue</tt> and corresponding value in child interface</td></tr>
<tr><td><tt>DOM_Document_getDoctype</tt></td><td>get the <tt>doctype</tt> node of the document</td></tr>
<tr><td><tt>DOM_Document_getDocumentElement</tt></td><td>get the <tt>documentElement</tt> of the document</td></tr>
<tr><td><tt>DOM_CharacterData_getLength</tt></td><td>get the <tt>length</tt> of a <tt>DOM_Text</tt>, <tt>DOM_Comment</tt>, <tt>DOM_CDATASection</tt>, or <tt>DOM_ProcessingInstruction</tt></td></tr>
</table>
<br clear="right"/>
<p/>
The all-important <tt>DOM_Node</tt> structure follows although some fields are left out in the interest of brevity. It may be necessary to look at this structure in the <tt>domc.h</tt> header.
<pre>
struct DOM_Node {
	DOM_String *nodeName;
	DOM_String *nodeValue;
	unsigned short nodeType;
	DOM_Node *parentNode;
	DOM_NodeList *childNodes;
	DOM_Node *firstChild;
	DOM_Node *lastChild;
	DOM_Node *previousSibling;
	DOM_Node *nextSibling;
	DOM_NamedNodeMap *attributes;
	DOM_Document *ownerDocument;
	union {
		struct {
			DOM_DocumentType *doctype;
			DOM_Element *documentElement;
			DOM_String *version;
			DOM_String *encoding;
			int standalone;
		} Document;
		struct {
			DOM_NamedNodeMap *entities;
			DOM_NamedNodeMap *notations;
			DOM_String *publicId;
			DOM_String *systemId;
			DOM_String *internalSubset;
		} DocumentType;
		struct {
			int specified;
			DOM_Element *ownerElement;
		} Attr;
		struct {
			int length;
		} CharacterData;
		struct {
			DOM_String *publicId;
			DOM_String *systemId;
		} Notation;
		struct {
			DOM_String *publicId;
			DOM_String *systemId;
			DOM_String *notationName;
		} Entity;
		struct {
			DOM_String *target;
			DOM_String *data;
		} ProcessingInstruction;
	} u;
};
</pre>
</desc>

<group>
<title>The DOM_Node functions</title>

<meth name="insertBefore" wrap="true">
<pre>DOM_Node *DOM_Node_insertBefore(DOM_Node *this, DOM_Node *newChild, DOM_Node *refChild);</pre>
<param name="this"/>
<param name="newChild"/>
<param name="refChild"/>
<desc>
The <tt>DOM_Node_insertBefore</tt> function inserts the node <tt>newChild</tt> into this node directly before the existing child <tt>refChild</tt>. If <tt>refChild</tt> is a null pointer, <tt>newChild</tt> will be appended to the list. If <tt>newChild</tt> is a <tt>DOM_DocumentFragment</tt> node, all children are moved into <tt>this</tt> node in the same order before <tt>refChild</tt>. If <tt>newChild</tt> is already in the list it will first be removed.
</desc>
<ret>The <tt>DOM_Node_insertBefore</tt> function returns a pointer to the node that was inserted.</ret>
</meth>

<meth name="replaceChild" wrap="true">
<pre>DOM_Node *DOM_Node_replaceChild(DOM_Node *this, DOM_Node *newChild, DOM_Node *oldChild);</pre>
<param name="this"/>
<param name="newChild"/>
<param name="oldChild"/>
<desc>
Replaces the child node <tt>oldChild</tt> with <tt>newChild</tt> in the list of children, and returns the <tt>oldChild</tt> node.<p/>
If <tt>newChild</tt> is a <tt>DocumentFragment</tt> object, <tt>oldChild</tt> is replaced by all of the <tt>DocumentFragment</tt> children, which are inserted in the same order. If the <tt>newChild</tt> is already in the tree, it is first removed.
</desc>
<ret>The node replaced.</ret>
</meth>

<meth name="removeChild">
<pre>DOM_Node *DOM_Node_removeChild(DOM_Node *this, DOM_Node *oldChild);</pre>
<param name="this"/>
<param name="oldChild"/>
<desc>
Removes the child node indicated by <tt>oldChild</tt> from the list of children, and returns it.
</desc>
<ret>The node removed.</ret>
</meth>

<meth name="appendChild">
<pre>DOM_Node *DOM_Node_appendChild(DOM_Node *this, DOM_Node *newChild);</pre>
<param name="this"/>
<param name="newChild"/>
<desc>
The <tt>DOM_Node_appendChild</tt> function appends <tt>newChild</tt> at the end of the <tt>childNodes</tt> list of <tt>this</tt> node. If <tt>newChild</tt> is already in the list, it is first removed.
</desc>
<ret>The <tt>DOM_Node_appendChild</tt> function returns a pointer to <tt>newChild</tt> or a null pointer if the operation failed in which case <tt>DOM_Exception</tt> will be set appropriately.</ret>
</meth>

<meth name="hasChildNodes">
<pre>int DOM_Node_hasChildNodes(DOM_Node *this);</pre>
<param name="this"/>
<desc>
The <tt>DOM_Node_hasChildNodes</tt> function returns 1 if <tt>this</tt> node contains children and 0 if <tt>this</tt> node does not support child nodes or currently does not have any child nodes.
</desc>
</meth>

<meth name="cloneNode">
<pre>DOM_Node *DOM_Node_cloneNode(DOM_Node *this, int deep);</pre>
<param name="this"/>
<param name="deep"/>
<desc>
The <tt>DOM_Node_cloneNode</tt> function creates a copy of <tt>this</tt> node. If the <tt>deep</tt> parameter is not 0 all children will be cloned as well. The cloned node's <tt>parentNode</tt> pointer is <tt>NULL</tt>. Cloning a <tt>DOM_Element</tt> node copies all attributes regardless of what the <tt>deep</tt> parameter is. It is possibly to clone every node type with DOMC whereas the W3C specifications do not require cloning <tt>DOM_Document</tt>, <tt>DOM_DocumentType</tt>, <tt>DOM_Entity</tt>, and <tt>DOM_Notation</tt> nodes.
<p/>
The DOM specification requires that cloning an attribute node directly will return a specified attribute opposed to an attribute resulting from a default value specified in the DTD. Currently DOMC does not consider DTD default values. The value of <tt>attr->u.Attr.specified</tt> will always be 0.
</desc>
<ret>The <tt>DOM_Node_cloneNode</tt> function returns the new cloned node or a null pointer if the operation failed in whhich case <tt>DOM_Exception</tt> will be set appropriately.</ret>
</meth>

<meth name="normalize">
<pre>void DOM_Node_normalize(DOM_Node *this);</pre>
<param name="this"/>
<desc>
The <tt>DOM_Node_normalize</tt> function merges adjecent <tt>DOM_Text</tt> node content into &quot;normal&quot; form in the subtree of <tt>this</tt> node. Empty <tt>DOM_Text</tt> nodes will also be removed. When a document is first loaded it is in &quot;normal&quot; form.
</desc>
</meth>

</group>
</interface>

