New to Telerik UI for WinForms? Start a free 30-day trial

IDocument

Interface

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.

Definition

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

Assembly:Telerik.WinControls.RichTextEditor.dll

Syntax:

public interface IDocument : INode

Inherited Members INode.InsertBefore(INode, INode)INode.ReplaceChild(INode, INode)INode.RemoveChild(INode)INode.AppendChild(INode)INode.HasChildNodes()INode.CloneNode(bool)INode.Normalize()INode.IsSupported(string, string)INode.HasAttributes()INode.NodeNameINode.NodeValueINode.NodeTypeINode.ParentNodeINode.ChildNodesINode.FirstChildINode.LastChildINode.PreviousSiblingINode.NextSiblingINode.AttributesINode.OwnerDocumentINode.NamespaceURIINode.PrefixINode.LocalName...

Properties

Doctype

IDocumentType

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

removeNode

IDocumentType Doctype { get; }

DocumentElement

IElement

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".

IElement DocumentElement { get; }

Implementation

IDomImplementation

The

DOMImplementation

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

IDomImplementation Implementation { get; }

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.

IAttr CreateAttribute(string name)

Parameters:namestring

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.

IAttr CreateAttributeNS(string namespaceUri, string qualifiedName)

Parameters:namespaceUristring

The namespace URI of the attribute to create.

qualifiedNamestring

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

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

csharp

namespaceURI

csharp

null

csharp

qualifiedName

csharp

namespaceURI

http://www.w3.org/XML/1998/namespace", or if the

csharp

qualifiedName

csharp

namespaceURI

http://www.w3.org/2000/xmlns/".

CreateCdataSection(string)

Creates a

CDATASection

node whose value is the specified string.

ICdataSection CreateCdataSection(string data)

Parameters:datastring

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.

CreateDocumentFragment()

Creates an empty

DocumentFragment

object.

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.

IElement CreateElement(string tagName)

Parameters:tagNamestring

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.

IElement CreateElementNS(string namespaceUri, string qualifiedName)

Parameters:namespaceUristring

The namespace URI of the element to create.

qualifiedNamestring

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

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

csharp

namespaceURI

csharp

null

csharp

qualifiedName

csharp

namespaceURI

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

null

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

IEntityReference CreateEntityReference(string name)

Parameters:namestring

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.

IProcessingInstruction CreateProcessingInstruction(string target, string data)

Parameters:targetstring

The target part of the processing instruction.

datastring

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.

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

IElement GetElementById(string elementId)

Parameters:elementIdstring

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.

INodeList GetElementsByTagName(string tagName)

Parameters:tagNamestring

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.

INodeList GetElementsByTagNameNS(string namespaceUri, string localName)

Parameters:namespaceUristring

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

localNamestring

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, bool)

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

parentNode

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.

INode ImportNode(INode importedNode, bool deep)

Parameters:importedNodeINode

The node to import.

deepbool

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.

IDocument

Definition

Properties

Doctype

DocumentElement

Implementation

Methods

CreateAttribute(string)

CreateAttributeNS(string, string)

CreateCdataSection(string)

CreateComment(string)

CreateDocumentFragment()

CreateElement(string)

CreateElementNS(string, string)

CreateEntityReference(string)

CreateProcessingInstruction(string, string)

CreateTextNode(string)

GetElementById(string)

GetElementsByTagName(string)

GetElementsByTagNameNS(string, string)

ImportNode(INode, bool)