C++
int acdbEntMake( const struct resbuf * ent );
File
acedads.h
Description
Makes a new entity, which can be an empty dictionary, by appending the entity specified by ent to the drawing database. The ent argument is a linked list of result buffers that should have the same format as a list returned by acdbEntGet().
With this function, an ObjectARX application expands the entity list by creating new entities and adding them to the drawing.
The list that ent specifies has the following restrictions:
- Cannot specify the entity's handle (DXF groups 5 and 105).
- Ignores fields associated with the object extension dictionary.
- The first or second buffer in the list must specify the entity type, which must be a valid DXF entity type.
- AutoCAD must recognize all objects (except layers) to which the entity list refers.
- As an exception,acdbEntMake() accepts new layer names.
- The list cannot specify a handle or other internal fields.
- acdbEntMake() cannot create viewport, xref, xdef, or xdep entities.
- You can create an entity on a frozen layer.
Before it appends the entity to the database, acdbEntMake() performs the same consistency checks on ent as the AutoCAD DXFIN command performs on data from a DXF file. After it appends the entity to the database, acdbEntMake() displays the new entity (including its subentities) on the graphics screen.
If acdbEntMake() succeeds, it returns RTNORM; if it cannot update the database, it returns RTREJ. When acdbEntMake() fails, it sets the system variable ERRNO to a value that indicates the reason for the failure. When acdbEntMake() creates the endblk of a block, it returns RTKWORD; the name of the block can be retrieved by a subsequent call to acedGetInput().
The object type of the object created by acdbEntMake() determines where the object will reside. For example, if a layer object is passed to acdbEntMake(), the object will reside in the layer symbol table. If a simple entity is given to acdbEntMake(), it will reside in the current space. A block record entity is not required to make a block definition with acdbEntMake(), but it is accepted if passed.
For legacy reasons, acdbEntMake() ignores DXF group code 100 data for the following entity types: AcDbTextAcDbAttributeAcDbAttributeDefinitionAcDbBlockBeginAcDbBlockEndAcDbSequenceEndAcDbBlockReferenceAcDbMInsertBlockAcDb2dVertexAcDb3dPolylineVertexAcDbPolygonMeshVertexAcDbPolyFaceMeshVertexAcDbFaceRecordAcDb2dPolylineAcDb3dPolylineAcDbArcAcDbCircleAcDbLineAcDbPointAcDbFaceAcDbPolyFaceMeshAcDbPolygonMeshAcDbTraceAcDbSolidAcDbShapeAcDbViewport
Creating Complex Entities
You create a complex entity (a polyline or block) by making multiple calls to acdbEntMake(). Use a separate call for each subentity.
When acdbEntMake() first receives an initial component for a complex entity, it creates a temporary file in which to gather the definition data (and extended data, if that is present).
For each subsequent acdbEntMake() call, the function checks to see if the temporary file exists. If the temporary file exists, acdbEntMake() appends the new subentity to the file. When acdbEntMake() completes the definition of the complex entity (that is, when acdbEntMake() receives an appropriate seqend or endblk subentity), acdbEntMake() checks the entity for consistency. If the entity is valid, acdbEntMake() adds it to the drawing. When the complex entity is complete, or when the file creation has been canceled, acdbEntMake() deletes the file.
The entity does not appear in the drawing database until the final, seqend, or endblk subentity has been passed to acdbEntMake(). In particular, you cannot use acdbEntLast() to retrieve the most recently created subentity for a complex entity that has not been completed.
As already implied, acdbEntMake() can construct only one complex entity at a time. If a complex entity is being created and acdbEntMake() receives invalid data or an entity that is not an appropriate subentity, acdbEntMake() rejects both the invalid entity and the entire complex entity. One implication of this statement is that you can cancel the creation of a complex entity by calling acdbEntMake() with a null pointer.
Block definitions begin with a block entity and end with an endblk subentity. You cannot nest block definitions, nor can you have them reference themselves. A block definition can contain references to other block definitions.
The acdbEntMake() function does not check for name conflicts in the block definitions section, so it can overwrite existing blocks. Before you use it to create a block, use acdbTblSearch() to ensure that the name of the new block is unused.
When it successfully creates a block, acdbEntMake() returns a value of RTKWORD. Your program can then retrieve the name of the new block by a call to acedGetInput() and use the new name to create an insert by invoking acdbEntMake() again.
Block insert references can include an attributes-follow flag (group 66). If present and equal to 1, a series of attribute (Attrib) entities is expected to follow the insert entity. The attribute sequence is terminated by a seqend subentity.
Polyline entities always include a vertices-follow flag (also group 66). The value of this flag must be 1, and the flag must be followed by a sequence of vertex entities and terminated by a seqend subentity.
Complex entities can exist in either model space or paper space but not both. If the current space is changed by invoking either MSPACE or PSPACE (with acedCmd() or acedCommand()) while a complex entity is under construction, a subsequent call to acdbEntMake() cancels the complex entity. This also occurs if the subentity has a 67 group whose value does not match the 67 group of the entity header.
Anonymous Blocks
The block definitions (BLOCK) section in a drawing can contain anonymous blocks, which AutoCAD creates to support hatch patterns and associative dimensioning. Anonymous blocks can be created also by acdbEntMake(), usually to contain entities that the user cannot access directly. Unreferenced anonymous blocks are purged from the BLOCK table whenever AutoCAD opens a new drawing. Anonymous blocks referenced by insert entities are not purged. You can use acdbEntMake() to create a block reference (insert) to an anonymous block (you cannot pass an anonymous block to the INSERT command). You can also use acdbEntMake() to redefine the block. You can modify the entities in a block (but not the block entity itself) with acdbEntMod().
The name (group 2) of an anonymous block has the form *Unnn, where nnn is a number generated by AutoCAD. Also, the low-order bit of an anonymous block's block type flag (group 70) is set to 1. When acdbEntMake() creates a block whose name begins with * and whose anonymous bit is set, AutoCAD treats this as an anonymous block and assigns it a name. Any characters that follow the * in the name string passed to acdbEntMake() are ignored.
The only way your program can obtain the name of a new anonymous block is that to retrieve the block name when acdbEntMake() returns RTKWORD.
Although a referenced anonymous block becomes permanent, the numeric portion of its name can change each time the drawing is opened. Applications cannot rely on anonymous block names remaining constant.
Creating and Modifying Symbol Table Entries
Call acdbEntMake() to create symbol table entries. The following restrictions apply:
- Active or invalid symbol table entries cannot be created.
- Name conflicts cannot occur except in the VPORT table.
Symbol tables themselves cannot be created with acdbEntMake(). To modify symbol table xdata, call acdbEntMod().
The acdbEntMake() and acdbEntMod() functions ignore the 70 group of symbol table entries.
Parameters
| Parameters | Description |
|---|---|
| ent | Input entity to be appended to the database |