acdbEntMod

C++

int acdbEntMod(
    const struct resbuf * ent
);

File

acedads.h

Description

Updates the definition data of the specified entity. The entity that acdbEntMod() modifies is specified by the result buffer that contains the entity's name (restype == -1); this should be the first result buffer in ent.

Note As of R13c4, acdbEntMod() can change the contents of a dictionary entry, as well as the associated xdata and persistent reactors.

This function complements acdbEntGet() by retrieving an entity with acdbEntGet(), modifying its entity list, and then passing the list back to the database with acdbEntMod(). This is the primary mechanism by which an ARX application updates the database. The following list describes restrictions on the database changes that acdbEntMod() can make.

• acdbEntMod() cannot change the entity's type or handle (DXF groups 5 and 105).
• acdbEntMod() ignores attempts to modify the object extension dictionary and persistent-reactor chain elements.
• AutoCAD must recognize all objects (except layers) that the entity list references.

The name of any text style, linetype, shape, or block that appears in an entity list must be defined in the current drawing before the entity list is passed to acdbEntMod().

• As an exception, acdbEntMod() accepts new layer names.

If the entity list refers to a layer name that has not been defined in the current drawing, acdbEntMod() creates a new layer. The attributes of the new layer are the standard default values used by the New option of the AutoCAD LAYER command.

• acdbEntMod() cannot change internal fields.

Any attempt to change an internal field--for example, the main entity name in a seqend subentity (restype == -2)--is simply ignored.

• acdbEntMod() cannot modify a viewport, xref, xdef, or xdep entities.

An attempt to modify a viewport, xref, xdef, or xdep entity is rejected.

Warning You can use acdbEntMod() to change a block definition. However, an attempt to make a block self-referencing is a fatal error that causes AutoCAD to exit. You may be able to recover other changes to the drawing by using the File menu's Recover option or the RECOVER command.

Before it updates the database, acdbEntMod() performs the same consistency checks on ent as the AutoCAD DXFIN command performs on data from a DXF file.

You can restore the default color or linetype of an entity by using acdbEntMod() to set the entity's color to 256 or the linetype to BYLAYER.

If ent specifies a main entity, acdbEntMod() redisplays the entity's screen image (including its subentities). However, if ent specifies a subentity (such as a polyline vertex or block attribute), acdbEntMod() does not redisplay the screen image. You can use the acdbEntUpd() function to redisplay the screen image. This distinction enables an application to perform a series of subentity modifications by using a series of calls to acdbEntMod() and then redisplaying the modified subentities with a single acdbEntUpd() call.

Warning If ent is in a block definition, then acdbEntUpd() is not sufficient. You must regenerate the drawing by invoking the AutoCAD REGEN command (with acedCmd() or acedCommand()) to ensure that all instances of the block references are updated.

If acdbEntMod() succeeds, it returns RTNORM; if it detects an error so serious that AutoCAD cannot update the database, it returns RTREJ. When acdbEntMod() fails, it sets the system variable ERRNO to a value that indicates the reason for the failure.

Note Before calling acdbEntMod() on vertex entities, read or write the polyline entity's header. If the most recently processed polyline entity is different from that of the vertex, width information (the 40 and 41 groups) can be lost.

Modifying Symbol Table Entries

Call acdbEntMod() to modify symbol data xdata and persistent reactors. Obtain the entity name of type ads_name by calling the acdbTblObjName() function. Next, call acdbEntGet() or acdbEntGetx(), not acdbTblSearch() or acdbTblNext(), to obtain a pointer to the entity itself. Call acdbEntMod() with the pointer to modify the symbol table entry's xdata or persistent reactors.

With the exception of xdata, the symbol table entries listed in the following table cannot be modified or renamed.

The symbol table entries listed in the following table can be modified but not renamed.

Notes on Processing Curve-Fit and Spline-Fit Polylines

When an ARX application uses acdbEntNext() to step through the vertices of a polyline, it may encounter a number of vertices that were not created explicitly; auxiliary vertices are inserted automatically by the AutoCAD PEDIT command's fit and spline options. You can safely ignore them, because changes to these vertices will be discarded the next time the user uses PEDIT to fit or spline the polyline.

The polyline entity's group 70 flags indicate whether the polyline has been curve-fit (bit value 2) or spline-fit (bit value 4). If neither of these bits is set, all of the polyline's vertices are normal. However, if the curve-fit bit (2) is set, alternating vertices of the polyline will have bit value 1 set in their 70 group to indicate that they were inserted by the curve-fitting process. If you use acdbEntMod() to move the vertices of such a polyline with the intent of refitting the curve using PEDIT, ignore these vertices.

Likewise, if the polyline entity's spline-fit flag bit (bit 4) is set, an assortment of vertices will be found, some with flag bit 1 (inserted by curve fitting if the SPLINESEGS system variable was negative), some with bit value 8 (inserted by spline fitting), and all others with bit value 16 (spline frame control point). Likewise, if you use acdbEntMod() to move the vertices and intend to refit the spline afterward, move only the control point vertices.

Parameters