Microsoft XML SDK 2.6 - XML Reference

IXMLDOMNode::text Method

IXMLDOMNode::get_text Method

Returns the string representing the text contents of this node or the concatenated text representing this node and its descendants.

Visual Basic Syntax

strValue = oXMLDOMNode.text

C/C++ Syntax

HRESULT get_text(
    BSTR *text);

Parameters

text
String representing the text content of this node and its descendants. This value varies depending on the value of the nodeType method (see below).

C/C++ Return Values

S_OK
Value returned if successful.
S_FALSE
Value returned when there is no text.
E_INVALIDARG
Value returned if text is Null.

Remarks

When concatenated, the text represents the contents of text or CDATA nodes. All concatenated text nodes are normalized according to xml:space attributes and the value of the preserveWhiteSpace switch. Concatenated CDATA text is not normalized. (Child nodes that contain NODE_COMMENT and NODE_PROCESSING_INSTRUCTION nodes are not concatenated.)

Note that if you need more precise control over text manipulation in an XML document, you may want to use the lower-level nodeValue method, which returns the raw text associated with a NODE_TEXT node.


IXMLDOMNode::put_text Method

Sets the text contents of this node or the concatenated text representing this node and its descendants.

Visual Basic Syntax

objXMLDOMNode.text = strValue

C/C++ Syntax

HRESULT put_text(
    BSTR *text);

Parameters

text
String representing the text content of this node and its descendants. This value varies depending on the value of the nodeType method (see below).

C/C++ Return Values

S_OK
Value returned if successful.
E_FAIL
Value returned if an error occurs.

Remarks

When concatenated, the text represents the contents of text or CDATA nodes. All concatenated text nodes are normalized according to xml:space attributes and the value of the preserveWhitespace switch. Concatenated CDATA text is not normalized. (Child nodes that contain NODE_COMMENT and NODE_PROCESSING_INSTRUCTION nodes are not concatenated.)

Note that if you need more precise control over text manipulation in an XML document, you may want to use the lower-level nodeValue method, which returns the raw text associated with a NODE_TEXT node.

Consider the "root" element in this example:

<root att="   123   a   <   ">
   <a>   a   a   </a>
   <!--   comment   b   -->
   <?pi   pi   c   ?>
   <![CDATA[   cdata   d   ]]>
   e   f
</root>

The text method for the root element returns the concatenated text:

"a a   cdata   d    e f"

Note that the white space within the CDATA node is preserved.

This value depends on the value of the nodeType method.

NODE_ATTRIBUTE,
NODE_DOCUMENT,
NODE_ENTITY		 Returns a string representing the value of the node. This is the concatenated text of all subnodes with entities expanded.
NODE_CDATA_SECTION,
NODE_COMMENT,
NODE_PROCESSING_INSTRUCTION,
NODE_TEXT		 Returns the text contained in the node, which is the same as the nodeValue method.
NODE_DOCUMENT_TYPE,
NODE_NOTATION		 Returns the empty string, "". These node types do not have associated text.
NODE_DOCUMENT_FRAGMENT Returns the text comprised of the concatenation of all descendant nodes.
NODE_ELEMENT Contains a string that represents the element content. Note that this will also include the text content from all child elements, concatenated in document order. For example, consider the following XML: 
<count>
  <item>one</item>
  <item>two</item>
  <item>three</item>
  <item>four</item>
</count>

The text method for the "count" element contains the value "onetwothreefour".
NODE_ENTITY_REFERENCE Returns the string representation of the entity reference.

Setting the text method is allowed only on nodes that allow write operations. It is not allowed on read-only nodes, such as NODE_DOCUMENT_FRAGMENT, NODE_DOCUMENT_TYPE, NODE_ENTITY, NODE_ENTITY_REFERENCE, and NODE_NOTATION.

Note that when writing this method, the supplied value applies to all nodes beneath it in the tree. Setting the text method has the result of deleting the nodes containing substructure and inserting a single new child text node with the supplied text. For example, consider the following XML:

<count>
  <item>one</item>
  <item>two</item>
  <item>three</item>
  <item>four</item>
</count>

Immediately after setting the text method of the count element node to zero, the XML method for that node contains the new value:

<count>zero</count>
</pre>

See Also

IXMLDOMNode Interface | Handling White Space