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

# IDLffXMLDOMDocument::CreateTreeWalker

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

Please note the following exceptions in tree-walking:

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

## Syntax

Result = Obj->[IDLffXMLDOMDocument::]CreateTreeWalker( 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 tree walkers's current position is set at this node. If the object reference is NULL, the walker’s current position is set to 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 tree walker is about to visit a node. The purpose of this function is to allow the walker to ask the IDL application if it should visit a particular node, and hence return it in response to a call to one of the tree walker’s navigation methods (e.g., IDLffXMLDOMTreeWalker::NextNode). The code in this function should analyze the incoming node and then return a value that instructs the walker to accept or reject the node.

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

The various tree-walker movement methods return nodes that are accepted by the filter function. The movement methods do not return nodes that are rejected or skipped by the filter function. The walker does not consider nodes that are children of a rejected node, but does consider children of nodes that are skipped.

The tree walker calls the filter function for the given node after making determinations with respect to the WHAT_TO_SHOW setting. However, unlike the node iterator, the walker still calls the filter function for nodes not meeting the WHAT_TO_SHOW criteria. This is required so that the filter function can direct the walker to either REJECT or SKIP a node whose type is not in the WHAT_TO_SHOW list. If the filter function returns ACCEPT for a node not meeting the WHAT_TO_SHOW criteria, the walker SKIPs the node. That is, a filter function cannot override the rejection of a node because of the WHAT_TO_SHOW setting; it can only direct the walker to REJECT or SKIP such a node.

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 tree walker on every call.
- USERDATA — an optional keyword parameter set by the tree walker 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 walker.

The function must return one of three scalar integer values:

Value | Function
1 | ACCEPT: the tree walker visits this node
2 | REJECT: the tree walker does not visit this node or its children
3 | SKIP: the tree walker does not visit this node, but considers the node’s children for visiting

If the function returns a value that is not supported, the tree walker visits the node, as if the return value were 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 tree walker calls the filter function.

Supplying this keyword without FILTER_NAME produces no effect on the tree walker.

### WHAT_TO_SHOW

Set this keyword to a scalar unsigned integer containing a bitmask, where each bit indicates types of nodes that the tree walker visits. If this keyword is not specified, the walker 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 tree walker performs the WHAT_TO_SHOW test for a node before calling any user-provided filter function.

## Version History

6.2 | Introduced