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:
Result = Obj->[IDLffXMLDOMDocument::]CreateTreeWalker( RootNode
[, FILTER_NAME=string] [, FILTER_USERDATA=variable] [, WHAT_TO_SHOW=value] )
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.
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:
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.
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.
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.
|
6.2 |
Introduced |