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