Routines (alphabetical) > Object Classes > File Format Object Classes > IDLffXMLDOMDocument::CreateNodeIterator

# IDLffXMLDOMDocument::CreateNodeIterator

The IDLffXMLDOMDocument::CreateNodeIterator function method is used to create an instance of an IDLffXMLDOMNodeIterator object. This function returns an object reference to that instance.

Please note the following exceptions in node iteration:

- Attributes are never children of DOM nodes, so they are not visited by the node iterator. Showing attributes is only meaningful when the iterator root node is an attribute.
- Entities are not part of the DOM tree, so they are not visited by the node iterator. Showing entities is only meaningful when the iterator root node is an entity.
- Notations are not part of the DOM tree, so they are not visited by the node iterator. Showing notations is only meaningful when the iterator root node is a notation.

## Syntax

Result = Obj->[IDLffXMLDOMDocument::]CreateNodeIterator( RootNode
[, FILTER_NAME=string] [, FILTER_USERDATA=variable]
[, WHAT_TO_SHOW=value] )

## Arguments

### RootNode

An object reference to an object that is a subclass of IDLffXMLDOMNode that refers to a node in the DOM tree. The iterator's current position is set immediately before this node. If this object reference is NULL, the iterator's current position is set immediately before the document node.

## Keywords

### FILTER_NAME

Set this keyword to a scalar string containing the name of an IDL function that is called each time the iterator is about to visit a node. The purpose of this function is to allow the iterator to ask the IDL application if it should visit a particular node, and hence return it in response to an IDLffXMLDOMNodeIterator::NextNode or IDLffXMLDOMNodeIterator::PreviousNode method call. The code in this function should analyze the incoming node and then return a value that instructs the iterator to accept or reject the node.

If this keyword is not specified, the node iterator visits every node.

Nodes that are accepted are returned by IDLffXMLDOMNodeIterator::NextNode and IDLffXMLDOMNodeIterator::PreviousNode. Nodes that are rejected are not returned by these methods.

The filter function is called by the iterator for the given node after the determinations are made with respect to the WHAT_TO_SHOW setting. Therefore, the filter function is not called for nodes that are rejected by the WHAT_TO_SHOW property.

The filter function specified by FILTER_NAME must have the following parameters:

- Node Object — an object reference to an instance of an IDLffXMLDOMNode subclass. This parameter is required and is supplied by the iterator on every call.
- USERDATA — an optional keyword parameter set by the iterator to a variable containing a copy of the data provided in the FILTER_USERDATA keyword. If FILTER_USERDATA is not specified, USERDATA is not passed by the iterator.

The function must return one of three scalar integer values:

Value | Function
1 | ACCEPT: this node is visited by the node iterator
2 | REJECT: this node is not visited by the node iterator
3 | SKIP: this node is not visited by the node iterator (same as REJECT)

SKIP and REJECT have the same meanings for a node iterator, but have different meanings for a tree walker. This makes it possible for a single filter function to be used with either a node iterator or tree walker. If the function returns a value that is not supported, the iterator visits the node, as if the return value was 1 (ACCEPT). If the function returns a value that cannot be converted to a scalar, IDL throws an error.

The function should not destroy the node object passed as the first parameter.

### FILTER_USERDATA

Set this keyword to an IDL variable containing data to pass to the filter function each time the iterator calls the filter function. The iterator creates a copy of this variable to pass on each call.

Supplying this keyword without FILTER_NAME produces no effect on the iterator.

### WHAT_TO_SHOW

Set this keyword to a scalar unsigned integer containing a bitmask, where each bit indicates types of nodes that the iterator visits. If this keyword is not specified, the node iterator visits every node.

Type | Value (Hex) | Value (Decimal)
ALL | ‘ffff’xu | 65535U
Element | ‘0001’xu | 1U
Attribute | ‘0002’xu | 2U
Text | ‘0004’xu | 4U
CDATA Section | ‘0008’xu | 8U
Entity Reference | ‘0010’xu | 16U
Entity | ‘0020’xu | 32U
Processing Instruction | ‘0040’xu | 64U
Comment | ‘0080’xu | 128U
Document | ‘0100’xu | 256U
Document Type | ‘0200’xu | 512U
Document Fragment | ‘0400’xu | 1024U
Notation | ‘0800’xu | 2048U

The node iterator performs the WHAT_TO_SHOW test for a node before calling any user-provided filter function.

## Version History

6.2 | Introduced