Microsoft XML 2.5 SDK


 

IXMLDOMNode::put_text Method

[This is preliminary documentation and subject to change.]

Contains the text content of the node and its subtrees.

Visual Basic Syntax

objXMLDOMNode.text = strValue

C/C++ Syntax

HRESULT put_text(

    BSTR *text);

Parameters

text

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

C/C++ Return Values

S_OK

Value returned if successful.

E_FAIL

Value returned if an error occurs.

Remarks

The string represents the text contents of this node or the concatenated text representing this node and its descendants. 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.)

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

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 property.
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 property for the "count" element contains the value "onetwothreefour".
NODE_ENTITY_REFERENCE Returns the string representation of the entity reference.

Setting the text property 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 property, the supplied value applies to all nodes beneath it in the tree. Setting the text property 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 property of the count element node to zero, the XML property for that node contains the new value: 

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

See Also

White space handling