The following C++ interfaces and methods are patterned after the Java implementation of the W3C DOM (Document Object Model) Level 1. For complete documentation of this interface, see the web site of the W3C Organization.
Because this interface supports C as well as C++, both return values and exceptions are supported. To enable exceptions for C++, you must call the enableExceptions method in the Document interface with a non-zero value.
All methods that are defined in the Java interfaces with a void return are defined in this interface to return a pointer to a DOMException interface.
For all other methods, if the return pointer is null, there was an error. Call the getLastError method of the Document interface to receive a DOMException interface that you can query for the error.
The DOM methods are grouped by the type of node the method interacts with. The Node interface has methods for general manipulation of nodes. Some of the methods return structures that can be manipulated with the following interfaces.
|
Method |
Returned Structure |
Interface |
|---|---|---|
|
getChildNodes |
NodeList |
|
|
DOMException |
|
|
getAttributes |
NamedNodeMap |
Some node types have specialized interfaces. The table below lists these nodes and their interfaces:
|
Node Type |
Interface |
|---|---|
|
Attribute |
|
|
Document |
|
|
Document Type |
|
|
Element |
|
|
Entity |
|
|
Notation |
|
|
Processing Instruction |
|
|
Text |
Some node types do not have a specialized interface. The following node types must be manipulated with the Node interface or the inherited interface from the parent node interface.
CDATASection Interface. The CDATASection interface inherits from the Text interface. CDATA sections are used to escape blocks of text containing characters that would otherwise be regarded as markup. The only delimiter that is recognized in a CDATA section is the “]]>” string that ends the CDATA section. CDATA sections can not be nested. The primary purpose is for including material such as XML fragments, without needing to escape all the delimiters.
The DOMString attribute of the Text node holds the text that is contained by the CDATA section. The text may contain characters that need to be escaped outside of CDATA sections and that, depending on the character encoding (“charset”) chosen for serialization, it may be impossible to write out some characters as part of a CDATA section.
The CDATASection interface inherits the CharacterData interface through the Text interface. Adjacent CDATASection nodes are not merged by use of the Element.normalize() method.
Comment Interface. The Comment interface inherits from the CharacterData interface and represents the contents of a comment. In other words, a comment node represents all the characters between the starting ’<!--’ and ending ’-->’. This is the definition of a comment in XML, and, in practice, HTML, although some HTML tools may implement the full SGML comment structure.
EntityReference Interface. The EntityReference interface inherits from the Node interface. Entity reference objects may be inserted into the structure model when an entity reference is in the source document, or when the user wishes to insert an entity reference. Character references and references to predefined entities are considered to be expanded by the HTML or XML processor so that characters are represented by their Unicode equivalent rather than by an entity reference. Moreover, the XML processor may completely expand references to entities while building the structure model, instead of providing EntityReference objects. If it does provide such objects, then for a given EntityReference node, it may be that there is no Entity node representing the referenced entity; but if such an Entity exists, then the child list of the EntityReference node is the same as that of the Entity node. As with the Entity node, all descendants of the EntityReference are read-only.
The resolution of the children of the EntityReference (the replacement value of the referenced Entity) may be lazily evaluated; actions by the user (such as calling the childNodes method on the EntityReference node) are assumed to trigger the evaluation.
Document Fragment. The DocumentFragment interface inherits from the Node interface and is a “lightweight” or “minimal” Document object and allows you to extract a portion of a document’s tree or to create a new fragment of a document.
Imagine implementing a user command like cut or rearranging a document by moving fragments around. It is desirable to have an object which can hold such fragments, and it is quite natural to use a Node for this purpose. While it is true that a Document object could fulfil this role, a Document object can potentially be a heavyweight object, depending on the underlying implementation. What is really needed for this is a very lightweight object. DocumentFragment is such an object and is created with the createDocumentFragment method of the Document interface.
Various operations—such as inserting nodes as children of another Node—may take DocumentFragment objects as arguments; this results in all the child nodes of the DocumentFragment being moved to the child list of this node.
The children of a DocumentFragment node are zero or more nodes, representing the tops of any sub-trees defining the structure of the document. DocumentFragment nodes do not need to be well-formed XML documents (although they do need to follow the rules imposed upon well-formed XML parsed entities, which can have multiple top nodes). For example, a DocumentFragment might have only one child and that child node could be a Text node. Such a structure model represents neither an HTML document nor a well-formed XML document.
When a DocumentFragment is inserted into a Document (or indeed any other Node that may take children), the children of the DocumentFragment and not the DocumentFragment itself are inserted into the Node. This makes the DocumentFragment very useful when the user wishes to create nodes that are siblings; the DocumentFragment acts as the parent of these nodes so that the user can use the standard methods from the Node interface, such as the insertBefore method and the appendChild method.