AcDbEntity::highlight

C++

ACDBCORE2D_PORT ADESK_SEALED_VIRTUAL Acad::ErrorStatus highlight(
    const AcDbFullSubentPath& subId = kNullSubent, 
    const Adesk::Boolean highlightAll = false
) const;

Description

This function uses the AcDbFullSubentPathid to determine which subentity in the entity is desired. It then highlights that subentity on screen. If no AcDbFullSubentPath argument is provided, then the entire entity will be highlighted.

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

This function uses the entity's getGsMarkersAtSubentPath() method to get the GS markers associated with subId. If that function does not return Acad::eOk, then this function will fail and return whatever ErrorStatus was returned by getGsMarkersAtSubentPath().

If this function succeeds, then it returns Acad::eOk.

It is not necessary to balance each highlight() function call with a corresponding call to unhighlight(). Calling the unhighlight() function will unhighlight the entity designated by subId regardless of how many times the highlight function has been called on it.

If the entity on which this method is called has its graphics queued for regeneration (that is, changes have been made to the entity but have not yet been reflected on screen), then this method will not cause a highlight to occur. Also, calling this method on an entity that's open for write and whose graphics are queued for regeneration may terminate AutoCAD.

To avoid this limitation, before calling highlight(), you should flush the entity's graphics by either calling the entity's draw() method, or calling the AcTransactionManager::flushGraphics() function.

The AcDbEntity::highlight() implementation does all the work necessary to highlight any subentities that correspond to the subIdFullSubentPath. So, there is no need to override this method unless you wish to do some pre-or post-processing, or you wish to disable the ability to highlight subentities.

If this method is overridden and it is supposed to highlight subentities, then the AcDbEntity::highlight() method will need to be invoked at some point within this function in order to do the actual highlighting.

Within the AcDbEntity::highlight() method, the getGsMarkersAtSubentPath() method of this entity is called to translate the FullSubentPath into the corresponding GS markers. So, if this function is to succeed, the getGsMarkersAtSubentPath() method needs to be implemented as well.

For more information on the subIdAcDbFullSubentPath argument, see the documentation on the getGsMarkersAtSubentPath() or getSubentPathsAtGsMarker() methods.

Parameters

Links

AcDbEntity