Handling Hard References to AcDbEntities During wblockClone()

If you create a custom object with either an AcDbHardPointerId or a hard-coded reference to an AcDbEntity, you are responsible for calling AcDbBlockTableRecord::appendAcDbEntity() on the referenced entity, when needed during wblock(). In this context, a hard-coded reference is any situation in which an object causes an entity to be included in a wblockClone() via some custom code written in an application.

It is necessary to do the appending manually because the default implementation of AcDbDatabase::wblockClone() will always set isPrimary to Adesk::kFalse when calling wblockClone() on referenced objects. If the object is an AcDbEntity, this setting tells wblockClone() to not append the entity. However, as indicated in the previous section, if we are not doing a WBLOCK* and the cloned entity is to occupy model space or paper space, then the default behavior must be overridden and the append must be called.

If you allow the default behavior to occur in the call to wblockClone() the entity, its clone will end up in the database, but it will be ownerless. It will not have been appended to its new owner, and there is no current way to complete its append via the API. For the referenced entity to be appended, the isPrimary value must be reset to Adesk::kTrue before calling its wblockClone() function.

Note: Custom objects that use the default AcDbObject::wblockClone() implementation and reside in the named objects dictionary must implement their dwgOutFields() and dwgInFields() functions. These functions should file the object ID of their owner as a hard pointer ID when the filer type is AcDb::kWblockCloneFiler. This ensures that the owning object will also be included in the wblockClone() operation. Custom objects that are stored in extension dictionaries of other objects, or objects that have implemented their own wblockClone() method to take care of including the owner, do not need to file their owner's object ID.

The following two cases show how one might handle a hard reference from a custom object to another entity. The first case is simpler, but it requires that the referring and referenced entities always exist in the same AcDbBlockTableRecord. The second shows what must be considered if the two entities can exist in different records, or when the reference is in an AcDbObject instead of an AcDbEntity.