Interface IDocument

The

Document

interface represents the entire HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data.

Since elements, text nodes, comments, processing instructions, etc. cannot exist outside the context of a

Document

, the

Document

interface also contains the factory methods needed

to create these objects. The

Node

objects created have a

ownerDocument

attribute which associates them with the

Document

within whose context they were created.

See also the Document Object Model (DOM) Level 2 Core Specification.

Inherited Members

INode.InsertBefore(INode, INode)

INode.ReplaceChild(INode, INode)

INode.RemoveChild(INode)

INode.AppendChild(INode)

INode.HasChildNodes()

INode.CloneNode(Boolean)

INode.Normalize()

INode.IsSupported(String, String)

INode.HasAttributes()

INode.NodeName

INode.NodeValue

INode.NodeType

INode.ParentNode

INode.ChildNodes

INode.FirstChild

INode.LastChild

INode.PreviousSibling

INode.NextSibling

INode.Attributes

INode.OwnerDocument

INode.NamespaceURI

INode.Prefix

INode.LocalName

Namespace: Telerik.WinForms.Documents.FormatProviders.Html.Parsing.Dom

Assembly: Telerik.WinControls.RichTextEditor.dll

Syntax

public interface IDocument : INode

Properties

Doctype

The Document Type Declaration (see

DocumentType

) associated with this document. For HTML documents as well as XML documents without a document type declaration this returns

null

. The DOM Level 2 does not support editing the

Document Type Declaration.

docType

cannot be altered in any way, including through the use of methods inherited from the

Node

interface, such as

insertNode

or

removeNode

.

Declaration

IDocumentType Doctype { get; }

Property Value

IDocumentType

DocumentElement

This is a convenience attribute that allows direct access to the child node that is the root element of the document. For HTML documents, this is the element with the tagName "HTML".

Declaration

IElement DocumentElement { get; }

Property Value

IElement

Implementation

The

DOMImplementation

object that handles this document. A DOM application may use objects from multiple implementations.

Declaration

IDomImplementation Implementation { get; }

Property Value

IDomImplementation

Methods

CreateAttribute(String)

Creates an

Attr

of the given name. Note that the

Attr

instance can then be set on an

Element

using the

setAttributeNode

method.
To create an attribute with a qualified name and namespace URI, use the

createAttributeNS

method.

Declaration

IAttr CreateAttribute(string name)

Parameters

System.String name The name of the attribute.

Returns

IAttr A new Attr object with the nodeName attribute set to name , and localName , prefix , and namespaceURI set to null . The value of the attribute is the empty string.

Exceptions

DomException INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

CreateAttributeNS(String, String)

Creates an attribute of the given qualified name and namespace URI. HTML-only DOM implementations do not need to implement this method.

Declaration

IAttr CreateAttributeNS(string namespaceUri, string qualifiedName)

Parameters

System.String namespaceUri The namespace URI of the attribute to create.

System.String qualifiedName The qualified name of the attribute to instantiate.

Returns

IAttr A new Attr object with the following attributes: AttributeValue Node.nodeName qualifiedName Node.namespaceURI namespaceURI Node.prefix prefix, extracted from qualifiedName , or null if there is no prefix Node.localName local name, extracted from qualifiedName Attr.name qualifiedName Node.nodeValue the empty string

Exceptions

DomException INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character. NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null , if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from " http://www.w3.org/XML/1998/namespace";, or if the qualifiedName is "xmlns" and the namespaceURI is different from " http://www.w3.org/2000/xmlns/";.

CreateCdataSection(String)

Creates a

CDATASection

node whose value is the specified string.

Declaration

ICdataSection CreateCdataSection(string data)

Parameters

System.String data The data for the CDATASection contents.

Returns

ICdataSection The new CDATASection object.

Exceptions

DomException NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

CreateComment(String)

Creates a

Comment

node given the specified string.

Declaration

IComment CreateComment(string data)

Parameters

System.String data The data for the node.

Returns

IComment The new Comment object.

CreateDocumentFragment()

Creates an empty

DocumentFragment

object.

Declaration

IDocumentFragment CreateDocumentFragment()

Returns

IDocumentFragment A new DocumentFragment .

CreateElement(String)

Creates an element of the type specified. Note that the instance returned implements the

Element

interface, so attributes can be specified directly on the returned object.
In addition, if there are known attributes with default values,

Attr

nodes representing them are automatically created

and attached to the element.
To create an element with a qualified name and namespace URI, use the

createElementNS

method.

Declaration

IElement CreateElement(string tagName)

Parameters

System.String tagName The name of the element type to instantiate. For XML, this is case-sensitive. For HTML, the tagName parameter may be provided in any case, but it must be mapped to the canonical uppercase form by the DOM implementation.

Returns

IElement A new Element object with the nodeName attribute set to tagName , and localName , prefix , and namespaceURI set to null .

Exceptions

DomException INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

CreateElementNS(String, String)

Creates an element of the given qualified name and namespace URI. HTML-only DOM implementations do not need to implement this method.

Declaration

IElement CreateElementNS(string namespaceUri, string qualifiedName)

Parameters

System.String namespaceUri The namespace URI of the element to create.

System.String qualifiedName The qualified name of the element type to instantiate.

Returns

IElement A new Element object with the following attributes:AttributeValue Node.nodeName qualifiedName Node.namespaceURI namespaceURI Node.prefix prefix, extracted from qualifiedName , or null if there is no prefix Node.localName local name, extracted from qualifiedName Element.tagName qualifiedName

Exceptions

DomException INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character. NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null , or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from " http://www.w3.org/XML/1998/namespace"; .

CreateEntityReference(String)

Creates an

EntityReference

object. In addition, if the referenced entity is known, the child list of the

EntityReference

node is made the same as that of the

corresponding

Entity

node.If any descendant of the

Entity

node has an unbound namespace prefix, the

corresponding descendant of the created

EntityReference

node is also unbound; (its

namespaceURI

is

null

). The DOM Level 2 does not support any mechanism to

resolve namespace prefixes.

Declaration

IEntityReference CreateEntityReference(string name)

Parameters

System.String name The name of the entity to reference.

Returns

IEntityReference The new EntityReference object.

Exceptions

DomException INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character. NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

CreateProcessingInstruction(String, String)

Creates a

ProcessingInstruction

node given the specified name and data strings.

Declaration

IProcessingInstruction CreateProcessingInstruction(string target, string data)

Parameters

System.String target The target part of the processing instruction.

System.String data The data for the node.

Returns

IProcessingInstruction The new ProcessingInstruction object.

Exceptions

DomException INVALID_CHARACTER_ERR: Raised if the specified target contains an illegal character. NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

CreateTextNode(String)

Creates a

Text

node given the specified string.

Declaration

IText CreateTextNode(string data)

Parameters

System.String data The data for the node.

Returns

IText The new Text object.

GetElementById(String)

Returns the

Element

whose

ID

is given by

elementId

. If no such element exists, returns

null

. Behavior is not defined if more than one element

has this

ID

. The DOM implementation must have information that says which attributes are of type ID. Attributes with the name "ID" are not of type ID unless so defined. Implementations that do not know whether attributes are of type ID or not are expected to return

null

.

Declaration

IElement GetElementById(string elementId)

Parameters

System.String elementId The unique id value for an element.

Returns

IElement The matching element.

GetElementsByTagName(String)

Returns a

NodeList

of all the

Elements

with a given tag name in the order in which they are encountered in a preorder traversal of the

Document

tree.

Declaration

INodeList GetElementsByTagName(string tagName)

Parameters

System.String tagName The name of the tag to match on. The special value "*" matches all tags.

Returns

INodeList A new NodeList object containing all the matched Elements .

GetElementsByTagNameNS(String, String)

Returns a

NodeList

of all the

Elements

with a given local name and namespace URI in the order in which they are encountered in a preorder traversal of the

Document

tree.

Declaration

INodeList GetElementsByTagNameNS(string namespaceUri, string localName)

Parameters

System.String namespaceUri The namespace URI of the elements to match on. The special value "*" matches all namespaces.

System.String localName The local name of the elements to match on. The special value "*" matches all local names.

Returns

INodeList A new NodeList object containing all the matched Elements .

ImportNode(INode, Boolean)

Imports a node from another document to this document. The returned node has no parent; (

parentNode

is

null

). The source node is not altered or removed from the original document; this method creates a new copy of the source node.
For all nodes, importing a node creates a node object owned by the importing document, with attribute values identical to the source node's

nodeName

and

nodeType

, plus the attributes related to namespaces (

prefix

,

localName

, and

namespaceURI

). As in the

cloneNode

operation on a

Node

, the source

node is not altered.
Additional information is copied as appropriate to the

nodeType

, attempting to mirror the behavior expected if

a fragment of XML or HTML source was copied from one document to another, recognizing that the two documents may have different DTDs in the XML case. The following list describes the specifics for each type of node.

ATTRIBUTE_NODE

The

ownerElement

attribute is set to

null

and the

specified

flag is set to

true

on the generated

Attr

. The descendants of the source

Attr

are recursively imported and the resulting nodes reassembled to form the corresponding subtree. Note that the

deep

parameter has no effect on

Attr

nodes; they always carry their children with them

when imported.

DOCUMENT_FRAGMENT_NODE

If the

deep

option was set to

true

, the descendants of the source element are recursively imported and the resulting nodes reassembled to form the corresponding subtree. Otherwise, this simply generates an empty

DocumentFragment

.

DOCUMENT_NODE

Document

nodes cannot be imported.

DOCUMENT_TYPE_NODE

DocumentType

nodes cannot be imported.

ELEMENT_NODE

Specified attribute nodes of the source element are imported, and the generated

Attr

nodes are attached to the generated

Element

. Default attributes are not copied, though if the document being imported into defines default attributes for this element name, those are assigned. If the

importNode

deep

parameter was set to

true

, the descendants of the source element are

recursively imported and the resulting nodes reassembled to form the corresponding subtree.

ENTITY_NODE

Entity

nodes can be imported, however in the current release of the DOM the

DocumentType

is readonly. Ability to add these imported

nodes to a

DocumentType

will be considered for addition to a future release of the DOM.On import, the

publicId

,

systemId

, and

notationName

attributes are

copied. If a

deep

import is requested, the descendants of the the source

Entity

are recursively imported and the resulting nodes reassembled to form the corresponding subtree.

ENTITY_REFERENCE_NODE

Only the

EntityReference

itself is copied, even if a

deep

import is requested, since the source and destination documents might have defined the entity differently. If the document being imported into provides a definition for this entity name, its value is assigned.

NOTATION_NODE

Notation

nodes can be imported, however in the current

release of the DOM the

DocumentType

is readonly. Ability to add these imported nodes to a

DocumentType

will be considered for addition to a future release of the DOM.On import, the

publicId

and

systemId

attributes are copied.

Note that the

deep

parameter has no effect on

Notation

nodes since they never have any children.

PROCESSING_INSTRUCTION_NODE

The imported node copies its

target

and

data

values from those of the

source node.

TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE

These three types of nodes inheriting from

CharacterData

copy their

data

and

length

attributes from those of

the source node.

Declaration

INode ImportNode(INode importedNode, bool deep)

Parameters

INode importedNode The node to import.

System.Boolean deep If true , recursively import the subtree under the specified node; if false , import only the node itself, as explained above. This has no effect on Attr , EntityReference , and Notation nodes.

Returns

INode The imported node that belongs to this Document .

Exceptions

DomException NOT_SUPPORTED_ERR: Raised if the type of node being imported is not supported.

Extension Methods

SvgExtentions.Traverse<T>(T, Func<T, IEnumerable<T>>)

SvgExtentions.TraverseDepthFirst<T>(T, Func<T, IEnumerable<T>>)