AcDbEntity::subentPtr

C++

ACDBCORE2D_PORT ADESK_SEALED_VIRTUAL AcDbEntity* subentPtr(
    const AcDbFullSubentPath& id
) const;

Description

Function usage

This function uses the AcDbFullSubentPathid to determine which subentity in the entity is desired. It then creates a copy of that subentity using one of the classes derived from AcDbEntity so that the copy is a true "entity" that can be added to the database. If the function succeeds then a pointer to the resulting copy is returned, otherwise NULL is returned.

Typically the AcDbFullSubentPath object passed in via id will be obtained from the entity's AcDbEntity::getSubentPathsAtGsMarker() method. This guarantees that it is fully and properly filled in.

The copy will be created using dynamically allocated memory (that is, using the new operator), so if it is not added to the database it will need to be deleted when it's no longer needed.

Function implementation in derived classes

This function must be able to interpret the information in the AcDbFullSubentPathid to determine which subentity in the entity is desired. It then must create an object (using the C++ new so that it's dynamically allocated and can be added to a database later if desired) of the appropriate class derived from AcDbEntity and fill it in with the data necessary to make it a copy of the subentity just determined. The function then returns a pointer to the newly allocated and filled in entity.

The idAcDbFullSubentPath object has two parts, an array of objectIds containing all the container objects of the "main" entity (the entity on which this function is being called), and an embedded AcDbSubentId object which in turn has two elements: an index value and a SubentType.

The SubentType data item within the embedded AcDbSubentId should be used to determine what type of subentity is being looked for. Possible SubentTypes are:

• AcDb::kFaceSubentType
• AcDb::kEdgeSubentType
• AcDb::kVertexSubentType
• AcDb::kMlineSubentCache

It is up to the implementer of this function to decide what type of entity to create for each of the SubentTypes, but most commonly a face subentity will be copied as an AcDbFace, vertex subentities are usually an AcDbPoint object, and for edge subentities you have your choice of the appropriate curve entities such as AcDbArc, AcDbLine, AcDbCircle, AcDbSpline, etc. However, since the AcGi graphics primitives can only be lines, circles, arcs, xlines, and rays, those are most likely to be the entity types to use.

The index data item within the embedded AcDbSubentId is then used to determine exactly which subentity is to be copied.

Though the index value is often the same as the GS marker, there are no rules governing how to assign and interpret index values other than that the getSubentPathsAtGsMarker() method needs to be able to assign them properly and this function and the getGsMarkersAtSubentPath() must be able to interpret them to determine the corresponding GS marker(s).

If the "main" entity is not nested within BlockReferences, then the FullSubentPath's objectId array will contain only the objectId of the "main" entity and will not be needed by this function.

If the "main" entity is nested in one or more BlockReferences, then the AcDbObjectIdArray contains the objectIds of the objects that are the nested containers of the subentity. The list is in order from the "main" entity that the subentity is a part of, out to the outermost AcDbBlockReference that is in model or paper space.

This list of containers will need to be used to obtain the model coordinate system to World Coordinate System transform for each container and combine them to obtain the total transformation from the subentity's coordinate system out to the World Coordinate System.

(Another possibility could be to implement the entity class's worldDraw to call the getModelToWorldTransform() method in the AcGiWorldGeometry or AcGiViewportGeometry [depending on whether the class is using worldDraw() or viewportDraw()] object passed into it. Then cache the matrix returned since this will be the complete transformation matrix you need.)

Regardless of how the transformation matrix is obtained, it needs to be applied to the subentity's data to transform the data to WCS coordinates to be used by the new AcDb entity just created. The new entity will expect all its information to be in WCS coordinates.

If the function runs to completion then it should return a pointer to the newly created entity that copies the subentity. If anything goes wrong, then the function should simply return NULL.

Default implementation

Immediately returns NULL.

Parameters

Links

AcDbEntity