BimRv SDK: Create an Element Group

Yury Lebedev

June 09, 2023

You can create element groups by using the newGroup() method.

After you create an OdBmElementGroup instance, start a transaction prior to adding the ElementGroup to a database. Only after the ElementGroup is in the database should you call the newGroup() method. Below is an example implementation:

OdBmElementGroupPtr pElementGroup = OdBmElementGroup::createObject();
  pElementGroup->newGroup(arrElementIds, L"Group 1");

Passed members should not belong to any other element groups or assemblies. Also, a future group name should not be used in existing OdBmElementGroup instances.

The created ElementGroup depends on the passed element list:

  • Model group (of the OST_IOSModelGroups category) is created for regular view-independent elements.
  • A Detail group (of the OST_IOSDetailGroups category) is created if there are no regular elements but there is at least one view-specific but non-annotation element such as FilledRegion; other annotation elements are added to this group too.
  • An Attached group (of the OST_IOSAttachedDetailGroups category) is created in addition to a Model group if there are also annotation elements that can be associated with it.
  • If the passed element list contains only annotations, group creation fails with an eEmptySet error.

Model and Detail group members can be extended with other elements depending on initial element lists. For example, a Detail group can be extended with Sketch and SketchPlane elements depending on the view, FilledRegion can have dependent dimension and curve elements invisible by default, and so on.

Also there are several new elements added to the database when creating element groups:

  • Attached ElementGroup instances for annotations, if there are any.
  • ElementGroupType instances for each ElementGroup.
  • Hidden clones of each member element and ElementGroup instance to organize so-called "defining" groups.

The mentioned "defining" group represents a snapshot of the initial ElementGroup state in case it is changed in the future with new or excluded members. These "defining" groups are accessible via the getDefiningGroupInstId() method. A "defining" group and its member elements are marked with a non-empty UnplacedOwnerId header field. The isUnplaced() method returns true for their element headers. All such elements should be excluded from any element processing routines as they are for internal use only.