PropertyHandle :: OpenHierarchy - Open hierarchy property handle

The function opens a hierarchy property handle, which creates a property handle for bottom property handle. The function will duplicate the complete hierarchy including the top property handle. The function copies the selections from the source hierarchy, i.e. the result contains the same selected instance as the source hierarchy.

The function returns a property handle for the collection in the bottom property handle. Upper parent property handle, which have been created by the function, will be destructed automatically when destroying the bottom property handle. When no top property handle is passed or when the top property handle is not part of the source hierarchy, the returned hierarchy ends with the extent property handle for the bottom property handle.

One may access upper property handles by referring parent property handle with the GetParentProperty() function. Since all parents are copies, one may change the selection in any parent handle without danger.

When passing true (YES) for path option, the function will turn the property hierarchy into a path property, which automatically iterates on higher levels.

When the source handle is opened in write mode or when any of the property handles in the hierarchy are opened in write mode, the copy might refer to a write protected instance. One may use the Refresh() function to remove the write protection, after instances have been released in the other hierarchy.

The root for the hierarchy it the top handle of the hierarchy. Since this is a copy handle, the complete hierarchy will be closed, when closing the origin handle (or the extend node) implicitly or explicitly.

Depending on the copy_selection option the selection from the source path is copies as well, i.e. the property handles in the hierarchy are positioned to the same instance as in the appropriate source handle.