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 |