The ODA Common Data Access API is used by viewer-like applications such as ODA Visualize to access structural information and object properties of imported (open) databases. The structure is provided as a tree, where at least the nodes of the sheet are connected with the imported graphics via a unique ID. Specific levels of the hierarchy in the tree depend on the domain, as well as the connection of this perceived hierarchy with the database contents. The purpose is to provide the user with some means to view database files (drawings and models) in a simplified, universal form. Obtaining this information is based on the RxProperties mechanism (non-COM properties). The functionality is implemented in the RxCommonDataAccess.tx module.
Requirements for the Common Data Access tree at the RxProperties level
To create a hierarchical structure using the Common Data Access API, the database must have the following set of properties and attributes:
- Hierarchical tree nodes should have an ODAUniqueID property with an OdUInt64 type value. ODAUniqueID is used to link the tree node with visualization geometry.
- All objects that are required in the hierarchical tree must either have a property with the HierarchyLevel attribute or they must be included in the CollectionProperty of the parent object. This property must contain a reference to a child object (or objects for CollectionProperty). It is recommended to exclude unnecessary or service objects.
- If the object has nested objects, the property should have the CollectionProperty type and return, respectively, an array of references to these objects.
- The HierarchyLevel attribute can be set to the following values:
- Entity — A leaf element of a hierarchical tree.
- Block — Set of elements of the hierarchical structure that can be used in the tree several times.
- BlockReference — Element that serves as a reference to the hierarchical element of the "Block" type.
- Model — Set of elements of a hierarchical structure, which can be logically separated in the hierarchical tree.
- Database — Element that contains a reference to an external database.
- Hidden — Utility element that has no significant properties and can be hidden when displaying the tree in viewer applications.
- In most cases, it is necessary to inherit from the OdRxHierarchyLevelAttribute class and override the function virtual OdString value(OdRxValue& value); to determine the object type by its ID.
- It is recommended that DisplayAsAttribute for the objects involved in the formation of the hierarchical tree and the property cache do not return an empty string.
For example:
A database object contains the Model property (for example) of the CollectionProperty type with the attribute HierarchyLevel. The value of this attribute is Model. This property contains a collection of references to the objects — models.
Each model object contains the Entity property (for example) of the CollectionProperty type with the HierarchyLevel attribute. The value of the attribute is Entity. To determine the exact type of the item, the overloaded function virtual OdString value(OdRxValue& value); of the class OdRxHierarchyLevelAttribute is required.
The next article in this two-part series will contain an example of obtaining hierarchical information from the Common Data Access tree.