AcDbBlockReference

Class Hierarchy

AcRxObject
    AcGiDrawable
        AcDbObject
            AcDbEntity
                AcDbBlockReference
                    AcDbMInsertBlock
                    AcDbTable
                    AcDbViewRepBlockReference

C++

class AcDbBlockReference : public AcDbEntity;

File

dbents.h

Description

The AcDbBlockReference class represents the INSERT entity within AutoCAD. A block reference is used to place, size, and display an instance of the collection of entities within the AcDbBlockTableRecord that it references. In addition, block references can be the owner of AcDbAttribute entities (the list of which is automatically terminated by an AcDbSequenceEnd entity).

AcDbBlockReference set functions inherited from AcDbEntity ignore the doSubents argument because these subentities are attributes that are really special text entities and need to have their own individual properties (unlike polyline vertices, which are just data points).

Classes Derived from AcDbBlockReference

Classes derived from AcDbBlockReference must supermessage the base class's worldDraw() function and allow it to do the work of drawing the entities in the block table record. This allows the osnap code to distinguish the graphics for each entity in the block table record and automatically get each entity's osnap points without having to iterate through the block reference.

The derived class can draw any other graphics it wishes to and can add osnap points of its own, but AcDbBlockReference::worldDraw() must draw the block table record's entities. The derived class must override getOsnapPoints() and implement it to explicitly handle the insert osnap mode (because the insert point is the responsibility of the block reference) and do nothing for the other modes, then return Acad::eOk.

Remarks

When the entities within the AcDbBlockTableRecord referenced by the block reference are resolved for display, the WCS for the entities within the block table record is mapped onto a coordinate system, which is essentially the OCS of the block reference. The origin is translated to the block reference's position point and the X and Y axes are rotated around the Z axis by the amount of the block reference's rotation value. The rotation value is in radians with positive going counterclockwise when looking down the Z axis towards the origin.

Any X, Y, Z scaling of the block reference is applied to the entities relative to their perceived WCS coordinate axes. This makes it possible to orient a scaled version of the entities in any way desired.

The AcDbBlockRecord::blockTransform() function will return a matrix that represents the coordinate system mapping (including the scaling) described above.

AcDbEntity::getGeomExtents() returns the minimal bounding box, but getGeomExtents() on a block reference may return a larger volume.

The extents for a block are determined by first determining the sum of the bounding boxes for all of the block's entities. getGeomExtents() then applies its transformation on the resulting volume. If the transformation includes a rotation, the resulting bounding box will grow dependent on how the corners of the box rotate. If the block is not rotated in relation to (for example) WCS, getGeomExtents() will not return a larger bounding box.

Classes derived from AcDbBlockReference cannot append attributes. This is by design. A call to appendAttribute() on an object of a class derived from AcDbBlockReference will result in the error eIllegalEntityType.

Links

AcDbBlockReference Constructor, AcDbBlockReference Methods