Node properties and methods reference
This topic gives detailed information about all properties and methods of the Node object. The availability of a property or method with an actual Node object, however, depends on the type of the Node: MetaJob, MetaGroup, MetaDocument, MetaDatapage, and MetaPage.
Properties
Attributes
Returns the attribute collection (MetaCollection) of the current node. See Attributes.
Count
Not available in MetaPage
Returns the number of child nodes in the current node.
Fields
Returns the field collection (MetaCollection) of the current node. See Fields.
Index
Not available in MetaJob
Gets the index of the node in its parent.
Returns:
The index (0-based) at which the current node is found in the parent's node list.
Exception:
- EOleException: Index is lower than 0 or higher than Count-1.
NodeType
Returns a value representing the type (TNodeType) of the current node.
| Return value | Node type |
|---|---|
| 0 | Job |
| 2 | Group |
| 3 | Document |
| 5 | Datapage |
| 6 | Page |
In an Active Script environment, such as the Run Script task, the return value is a numerical value.
However, in environments where the TNodeType type is defined, the node types are ntJob, ntGroup, ntDocument, ntDatapage, and ntPage.
Parent
Not available in MetaPage
Returns the parent node of the current node.
Selected
Not available in MetaPage
Indicates whether or not the node is set to be printed (see Including or excluding nodes from the output). If a node has its Selected property set to true, all of its child that also have their own Selected property set to true will print. If Selected is false, its child will not print, regardless of their Selected status.
(reading) Returns:
True if the node is selected, false otherwise.
(writing) Parameters:
Select True to mark as selected to be printed, false if it is not to be printed.
SelectedCount
Not available in MetaPage
Returns the number of child nodes in the current node that are set to be output, meaning that they have their Selected property set to true, taking the parents into account.
Returns:
The number (integer) of child nodes that will be included in the output. If the current node and all of its parents have their Selected property set to true, this amounts to the number of child nodes that are selected. If any parent is not selected, returns 0.
SelectedState
Indicates whether the node is selected or not, taking its parents into account.
Returns:
Returns an integer indicating the selected state of the node. If the node and all of its parents are selected, the method returns ssTrue (2). If the node is selected but one of its parents is not, the return value is ssDisabled (1). If the node is not selected, the return value is ssFalse (0).
| Return value | State |
|---|---|
| 0 | False: The node is not selected. |
| 1 | Disabled: The node is selected but one of its parents is not. |
| 2 | True: The node and all of its parents are selected. |
Note: In an Active Script environment, such as the Run Script task, the return value is a numerical value.
However, in environments where the Selected State type is defined, the types are ssFalse (= 0), ssDisabled (= 1), and ssTrue (= 2).
Methods
Add(Integer Index)
Not available in MetaPage
Adds a new Node as a child of the current node.
Parameters:
Index
Specifies where in the child list to add the node. The node is inserted before the node at the specified index. In other words, the node being inserted becomes the node found at Index. To add a node at the start of the collection, use 0. To add it at the end, use Node.Count.
Returns:
Reference to the Node that was added.
Exception:
- EOleException: The value of Index is invalid.
AttributeByIndex(Integer Index)
Returns the value of the Metadata attribute at the specified index.
Parameters:
Index
0-based index of the attribute value to retrieve. The index of the first element is 0 and the index of the last is Count-1.
Returns:
The value of the attribute as a string.
Exception:
- EOleException: Index is lower than 0 or higher than Count-1.
AttributeByName(const String Name)
Returns the value of the metadata attribute of the specified name.
Parameters:
Name
Name of the attribute to retrieve.
Returns:
The value of the attribute as a string. If an attribute named Name is not found, an empty string is returned.
Clear()
Not available in MetaPage
Deletes all the child nodes of the current node, as well as all of its attributes and fields.
Copy()
Not available in MetaJob
Places a copy of the current node, along with all of its children, attributes and fields, in the metadata clipboard. Modifying the original node after the copy is made does not modify the copy in the clipboard.
Cut()
Not available in MetaJob
Places a copy of the current node, along with all of its children, attributes and fields, in the metadata clipboard and immediately removes the original from the Metadata structure.
Caution: The node being cut is removed immediately. Any reference to it or its child nodes becomes invalid. The results of calling methods of such references is undefined.
DatapageCount()
MetaJob and MetaGroup only
Returns the number of MetaDatapage nodes in all child nodes. This methods recursively goes through all child nodes to count the total number of MetaDatapage that are contained underneath the current node.
Returns:
Total number (integer) of MetaDatapage nodes found under the current node.
Delete()
Not available in MetaJob
Removes the current node, along with all of its children, attributes and fields, from the metadata structure.
Caution: The node being deleted is removed immediately. Any reference to it or its child nodes becomes invalid. The results of calling methods of such references is undefined.
DocumentCount()
MetaJob only
Returns the number of MetaDocument in all child nodes. This method recursively goes through all child nodes to count the total number of MetaDocument nodes that are contained underneath the current node.
Returns:
Total number (integer) of MetaDocument nodes found under the current node.
FieldByIndex(Integer Index)
Returns the value of the Metadata Field at the specified index. (See: Fields.)
Parameters:
Index
0-based index of the field value to retrieve. The index of the first element is 0 and the index of the last is Count-1.
Returns:
The value of the field as a string.
Exception:
- EOleException: Index is lower than 0 or higher than Count-1.
FieldByName(const String Name)
Returns the value of the Metadata Field of the specified name. (See: Fields.) If more than one field has the same name, this method returns the value of the first one it finds, starting at the first field in the list.
Parameters:
Name
Name of the field to retrieve.
Returns:
The value of the field as a string. If an field named Name is not found, an empty string is returned.
FieldByNameIndex(const String Name, Integer Index)
Returns the value of the n'th metadata field of the specified name. This method can be used to retrieve the value of a specific field when more than one field has the same name.
Parameters:
Name
Name of the field to retrieve.
Index
Ordinal of the field to retrieve. To retrieve the value of the first field named Name, use 0. For the second field, use 1, and so on.
Returns:
The value of the specified field as a string. If an field named Name is not found, or Index is higher or equal to the number of fields named Name (in other words, you specify 4 to get the fifth but there are only three), an empty string is returned.
Exception:
- EOleException: Index is lower than 0.
IndexInDocument()
MetaPage and MetaDatapage only
Returns the index of this page in its parent document, taking all the pages from all the datapages into account.
Returns:
Absolute index (integer, 0-based) of the page within all the pages under the parent document.
IndexInGroup()
MetaDocument, MetaDatapage and MetaPage only
Returns the index of this page in its parent group, taking all the pages from all the datapages from all documents into account.
Returns:
Absolute index (integer, 0-based) of the page within all the pages under the parent group.
IndexInJob()
Not available in MetaJob
Returns the index of this page in the job, taking all the pages from all the datapages from all the documents from all the groups into account.
Returns:
Absolute index (0-based) of the page within all the pages in the job.
Item(Integer Index)
Group ( Integer Index ) MetaJob only
Document ( Integer Index ) MetaGroup only
Datapage ( Integer Index ) MetaDocument only
Page ( Integer Index ) MetaDatapage only
Returns the child node located at the specified index.
Parameters:
Index
0-based index of the node to retrieve. The index of the first node is 0 and the index of the last is Count-1.
Returns:
Reference to the specified node.
Exception:
- EOleException: Index is lower than 0 or higher than Count-1.
PageCount()
MetaJob, MetaGroup and MetaDocument only
Returns the number of MetaPage in all child nodes. This methods recursively goes through all child nodes to count the total number of MetaPage that are contained underneath the current node.
Returns:
Total number of MetaPage found under the current node.
Paste()
Not available in MetaPage
Inserts the contents of the metadata clipboard as the last child node of the current node. This removes the node from the clipboard, making it empty after the paste operation.
Returns:
Reference to the top node being pasted.
Exception:
- EOleException: The node type of the clipboard and the current node don't match. For example, trying to paste a MetaGroup in a MetaGroup or a MetaPage in a MetaDocument.
PasteAt(Integer Index)
Not available in MetaPage
Inserts the contents of the metadata clipboard at the specified index in the current node. This removes the node from the clipboard, making it empty after the paste operation.
Parameters:
Index
Specifies where in the child list to add the node. The node is inserted before the node at the specified index. In other words, the node being inserted becomes the node found at Index. To add a node at the start of the collection, use 0. To add it at the end, use Node.Count.
Returns:
Reference to the top node being pasted.
Exceptions:
- EOleException: The node type of the clipboard and the current node don't match. For example, trying to paste a MetaGroup in a MetaGroup or a MetaPage in a MetaDocument.
- EOleException: The value of Index is invalid.
Select(TSelectWhat SelectWhat)
Not available in MetaPage
Changes the "selected" status of the current node as well as all of its child nodes according to the SelectWhat parameter.
Parameters:
SelectWhat
Indicates what to select. The value swNone changes the Selected property of the current node and all child nodes to false, while swAll changes it to true.
Script users: use 0 for swNone, 1 for swAll.
SelectedDatapageCount()
MetaJob and MetaGroup only
Returns the number of datapages under the current node that are set to be part of the output, i.e. that have their Selected property set to true, as well as all of their parents.
Returns:
The number of such nodes, if any. If the current node is not selected or one of its parents is not, it returns 0.
SelectedDocumentCount()
MetaJob only
Returns the number of documents under the current node that are set to be part of the output, i.e. that have their Selected property set to true, as well as all of their parents.
Returns:
The number of such nodes, if any. If the current node is not selected or one of its parents is not, it returns 0.
SelectedIndexInDocument()
MetaDatapage and MetaPage only
Returns the index of this page in its parent document, taking only the selected pages into account.
Returns:
Absolute index (0-based) of the page within all the selected pages under the parent document. If the page is not set to be output (i.e. its SelectedState is different than ssTrue), it returns -1.
SelectedIndexInGroup()
MetaDocument, MetaDatapage and MetaPage only
Returns the index of this page in its parent group, taking only the selected pages from all the datapages from all documents into account.
Returns:
Absolute index (0-based) of the page within all the selected pages under the parent group. If the page is not set to be output (i.e. its SelectedState is different than ssTrue), it returns -1.
SelectedIndexInJob()
Not available in MetaJob
Returns the index of this page in the job, taking only the selected pages from all the datapages from all the documents from all the groups into account.
Returns:
Absolute index (0-based) of the page within all the selected pages in the job. If the page is not set to be output (i.e. its SelectedState is different than ssTrue), it returns -1.
SelectedPageCount()
MetaJob, MetaGroup and MetaDocument only
Returns the number of pages under the current node that are set to be part of the output, i.e. that have their Selected property set to true, as well as all of their parents.
Returns:
The number of such nodes, if any. If the current node is not selected or one of its parents is not, it returns 0.
Sort(const String Name,
optional TSortFlags Flags,
optional const String Name2,
optional TSortFlags Flags2,
optional const String Name3,
optional TSortFlags Flags3)
Not available in MetaJob
Sorts the sub-nodes contained in the node according to a number of sort criteria. Unselected sub-nodes will be placed at the end, after all the selected sub-nodes, in the order in which they were placed prior to the sort.
Each of the three sort criteria can be modified by specifying one or more flags.
| Value | Meaning |
|---|---|
| 1 | The name refers to an Attribute rather than a field. |
| 2 |
|
| 4 | The field is an integer numeric value. |
Note: In an Active Script environment, such as the Run Script task, you must work with the numerical values.
In environments where the flags are defined, you may instead use sfAttribute (= 1), sfDescending (= 2), and sfNumeric (= 4).
All the parameters to this method except for the first one are optional. If a Name is specified, it must be valid for every sub-node. If, for example, the specified field is not found in a sub-node, or a numeric sort is performed and one of the values is not numeric (i.e. consists of only decimal characters, no thousand or decimal separator allowed), the method will fail.
If a sub-node contains multiple occurrences of fields with the specified name, only the first occurrence will be considered.
String comparisons are done without regards to the case (case-insensitive) using the Windows Win32 API function CompareString(LOCALE_USER_DEFAULT, NORM_IGNORECASE, ...).
Parameters:
Name
Name of the field or attribute contained in each sub-node whose value will be used as the first sort criteria. If it is an attribute instead of a field, this needs to be specified in the Flags parameter.
Flags (optional)
Set of flags that modify how the sorting on Name is done.
Name2 (optional)
Name of the field or attribute contained in each sub-node whose value will be used as the second sort criteria. If it is an attribute instead of a field, this needs to be specified in the Flags2 parameter.
Flags2 (optional)
Set of flags that modify how the sorting on Name2 is done.
Name3 (optional)
Name of the field or attribute contained in each sub-node whose value will be used as the third sort criteria. If it is an attribute instead of a field, this needs to be specified in the Flags3 parameter.
Flags3 (optional)
Set of flags that modify how the sorting on Name3 is done.
Exceptions:
- EOleException: Specified field or attribute does not exist in one of the sub-nodes.
- EOleException: A numeric sort is specified and one of the fields or attributes does not contain a valid numeric integer value.
- EOleException: An error occurred while comparing two strings.