AcDbEntity::setLayer

C++

virtual ACDBCORE2D_PORT Acad::ErrorStatus setLayer(
    const ACHAR* newVal, 
    Adesk::Boolean doSubents = true, 
    bool allowHiddenLayer = false
);

Description

This method sets entity to reference the AcDbLayerTableRecord identified by the name specified in newVal. If the entity owns subentities and doSubents == Adesk::kTrue, then the layer change will be applied to the subentities as well. For an AcDbBlockReference entity, this method will also update any associated AcDbSequenceEnd subentity regardless of the doSubents setting.

The only built-in entities for which kTrue has an effect are: AcDb2dPolyline, AcDb3dPolyline, AcDbPolyFaceMesh, and AcDbPolygonMesh.

The database containing the entity is searched for the AcDbLayerTableRecord object with the name pointed to by newVal. If the entity is not currently in a database, then the database currently in the AutoCAD editor is searched.

Specifying true for allowHiddenLayer allows newVal to denote a hidden layer. If this parameter is false (default) and newVal denotes a hidden layer the change request is silently ignored, and no error is returned.

If a matching LayerTableRecord is found then the entity will be set to reference it and Acad::eOk will be returned.

If no LayerTableRecord object is found with the name pointed to by newVal, then Acad::eKeyNotFound will be returned.

If the LayerTableRecord object found has been erased, then Acad::eDeletedEntry will be returned.

If the entity is not within a database and there is no database in the AutoCAD editor, then Acad::eNoDatabase will be returned.

Function implementation in derived classes

If this function is overridden and wishes to set the layer of the entity, then it must call AcDbEntity::setLayer() passing on the layer and doSubents arguments or call the other AcDbEntity::setLayer() passing in the doSubents value and the objectId of the AcDbLayerTableRecord to reference.

It is also possible for this function's implementation to deal directly with any subentities and pass a doSubents value of Adesk::kFalse to AcDbEntity::setLayer().

If this function is successful, it should return Acad::eOk. Any other error return values are up to the implementer, but if it calls either of the AcDbEntity::setLayer() methods and that call returns an error, then it's recommended that the ErrorStatus value returned be returned by this function as well.

Parameters

Links

AcDbEntity