company logo

Property :: openHierarchy - Open hierarchy property handle

The function opens a property handle hierarchy, which copies a property handle for bottom property handle passed in cBottomProperty. The function will duplicate the complete property handle hierarchy up to and including the top property, which is either the top-most property handle in the hierarchy or the property handle passed in rTopProperty. When the property handle is already opened, the current cursor will be released and a new cursor will be created.

In order to position the result property to the source property, the function may copy the selections from the source hierarchy.

The function returns a property handle for the collection in the bottom property. Upper parent property handle, which have been created by the function, will be destructed automatically when destroying the bottom property handle.

When the source handle is opened in write mode or when any of the property handles in the hierarchy is opened in write mode, the copy might refer to a write protected instance. You may use the refresh() function in order 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 of the top property handle.

The function returns the bottom property handle. You may access upper property handles by calling parentProperty(). Since all parents are copies, one may change the selection in any parent handle without danger.

Settings for filter, access key selection and auto-position are copied from source property handles. In case of an error, the function throws an exception.
Return value:  Property reference ( odaba::Property & )

A property handle refers to a (usually) opened property. Invalid properties may cause an exception.

Implementation overview

Implementation details

  1. Copy handle hierarchy
    odaba::Property & Property  :: openHierarchy ( odaba::Property &cBottomProperty, odaba::Property &cTopProperty )

    The function will duplicate the complete property handle hierarchy from cBottomProperty up to and including the top property handle passed in cTopProperty.

    Instances are not selected in the result property handle hierarchy. The access mode is the same as in source property handles.
    • cBottomProperty - Low property

      This is a pointer to the lowest property handle in a hierarchy or property path.
    • cTopProperty - High property handle

      This is a reference to the top property handle in a hierarchy or property path. When the property is empty (not opened), the top property handle is the extent, which is the root of the path.
    2. to list
  2. Create handle hierarchy and change access mode
    odaba::Property & Property  :: openHierarchy ( odaba::Property &cBottomProperty, odaba::Property &cTopProperty, odaba::AccessModes eAccessMode, bool bCopySelection )

    The function will duplicate the complete property handle hierarchy from cBottomProperty up to and including the top property handle passed in cTopProperty. In order to copy all property handles in the hierarchy up to and including the top-most property handle, an empty (invalid) property handle can be passed in cTopProperty.

    In order to change access mode for property handles in the target property hierarchy, eAccessMode has to be set to the access mode required.

    In order to copy selections to property handles in the result hierarchy, true has to be passed in bCopySelection. In this case, the result result property handle contains the same selected instance as cBottomProperty.

    • cBottomProperty - Low property

      This is a pointer to the lowest property handle in a hierarchy or property path.
    • cTopProperty - High property handle

      This is a reference to the top property handle in a hierarchy or property path. When the property is empty (not opened), the top property handle is the extent, which is the root of the path.
    • eAccessMode - Access mode

      Access mode for a property handle or database.
    • bCopySelection - Copy selection

      In order to copy selection from a source handles to the target handles, the option has to be set to true. In this case, target handles are positioned to the same instance as being selected in the source handle. The target handle is not positioned, when the option is set to false.
    3. to list
  3. Copy property handle hierarchy with selection
    odaba::Property & Property  :: openHierarchy ( odaba::Property &cBottomProperty, odaba::Property &cTopProperty, bool bCopySelection )

    The function will duplicate the complete property handle hierarchy from cBottomProperty up to and including the top property handle passed in cTopProperty. In order to change access mode for property handles in the target property hierarchy, eAccessMode has to be set to the access mode required.

    In order to copy selections to property handles in the result hierarchy, true has to be passed in bCopySelection. In this case, the result result property handle contains the same selected instance as cBottomProperty.

    The access mode is the same as in source property handles.
    • cBottomProperty - Low property

      This is a pointer to the lowest property handle in a hierarchy or property path.
    • cTopProperty - High property handle

      This is a reference to the top property handle in a hierarchy or property path. When the property is empty (not opened), the top property handle is the extent, which is the root of the path.
    • bCopySelection - Copy selection

      In order to copy selection from a source handles to the target handles, the option has to be set to true. In this case, target handles are positioned to the same instance as being selected in the source handle. The target handle is not positioned, when the option is set to false.
    4. to list
  4. Copy complete property handle hierarchy
    odaba::Property & Property  :: openHierarchy ( odaba::Property &cBottomProperty )

    The function will duplicate the complete property handle hierarchy from cBottomProperty up to and including its top-most property handle.

    Instances are not selected in the result property handle hierarchy. The access mode is the same as in source property handles.
    • cBottomProperty - Low property

      This is a pointer to the lowest property handle in a hierarchy or property path.
    5. to list
to top previous next upper table of contents Comment