PropertyHandle :: Position - Select an instance relative to the current selection
The function allow selecting an instance relatively to the currently selected instance. Thus the function allows selecting the next instance in the collection as Position(1) or the previous instance as Position(-1).
Calling the function with offset 0 (Position(0)), the function does not change selection, when an instance had been selected before. When no instance is selected in the property handle, the function positions the first instance in the collection.
When a filter has been set for the property handle, the function skips non accepted instances, i.e. only instances valid for the filter condition are counted.
The function returns NO when the instance could be selected. When no instance could be selected or an error occurred the function returns an error ( YES ).
In case of read arrors, the function returns an error, which is difficult to differ fron end of collection. Hence, the more secure way of reading instances in a collection is calling Get(index) and GetCount() in order to determin the zize of collection. In case of filter conditions for the collection, one may use GetRelativeCount() and GetAt(index).
Implementation details
- count
- Number of items
The value contains the number of items (characters, entries, instances etc.).