Use AutoCAD Map 3D's annotation feature to indicate textual values on a drawing object.
Setting Annotation Template Properties
Setting Annotation Text and Expressions
Inserting Annotation References
Annotation Samples Annotation Namespace
Before you can add annotation to a drawing, you first must call CreateAnnotationTemplate() to define an annotation template that specifies what information will be included and how it will be displayed. Call AnnotationTemplateExists() to check whether a specific template already exists; if it does exist, CreateAnnotationTemplate() won't overwrite it, but rather will return a null object ID.
For annotation source-code samples, see Annotation Samples.
char* pszTemplateName = "MyAnnotationTemplate";
AcDbObjectId idCreatedAnnTem;
if(!AnnotationTemplateExists(pszTemplateName))
{
// Create a template with the name stored in pszTemplateName.
idCreatedAnnTem = CreateAnnotationTemplate(pszTemplateName);
// Test whether the template's object ID is valid.
if(idCreatedAnnTem != AcDbObjectId::kNull)
{
}
}
Setting Annotation Template Properties
After creating an annotation template, you can retrieve or set its following static properties:
- Color - GetTemplateColor()/SetTemplateColor()
- Layer - GetTemplateLayer()/SetTemplateLayer()
- Linetype - GetTemplateLinetype()/SetTemplateLinetype()
- Lineweight - GetTemplateLineWeight()/SetTemplateLineWeight()
- Rotation - GetTemplateRotation()/SetTemplateRotation()
- Scale factor - GetTemplateScaleFactor()/SetTemplateScaleFactor()
For annotation source-code samples, see Annotation Samples.
Acad::ErrorStatus acErrStatus;
char* pszTemplateName = "MyAnnotationTemplate";
AcCmColor acclrInColor;
char* pszInLayerName = "aLayer";
// Set a few template properties.
acErrStatus = SetTemplateScaleFactor(pszTemplateName, 2.0);
acErrStatus = SetTemplateRotation(pszTemplateName, PI); // PI radians = 180 degrees
acclrInColor.setColorIndex(1); // Red.
acErrStatus = SetTemplateColor(pszTemplateName, acclrInColor);
acErrStatus = SetTemplateLayer(pszTemplateName, pszInLayerName);
// Get the scale factor.
double dOutScaleFactor;
acErrStatus = GetTemplateScaleFactor(dOutScaleFactor, pszTemplateName);
Setting Annotation Text and Expressions
To set the text that appears on an annotation, call CreateAnnotationText() to create a text object and set its properties (tag, height, color, justification, and so on), and then call SetExpressionString() to set the value that appears. The expression can be any valid combination of functions and variables that can appear in the AutoCAD Map 3D Expression Evaluator.One form of SetExpressionString() takes a char* expression, and the other form takes an AcMapExpression expression. To retrieve an expression, call GetExpressionString(). GetExpressionString() and SetExpressionString() take an eAnnotationExpressionFields argument that indicates which expression to retrieve or store. Use IsAnnotationText() to determine whether a particular attribute definition is an annotation text entity.
For annotation source-code samples, see Annotation Samples.
#include dbmain.h // Needed for acdbOpenObject().
Acad::ErrorStatus acErrStatus;
// idCreatedAnnTem was created earlier with CreateAnnotationTemplate().
AcDbObjectId idTagText;
acErrStatus = CreateAnnotationText(idTagText, idCreatedAnnTem);
// Open the newly created text object for write.
AcDbAttributeDefinition* pTagText = NULL;
acErrStatus = acdbOpenObject((AcDbObject *&)pTagText, idTagText, AcDb::kForWrite);
// Check if this is an annotation text object.
if (IsAnnotationText(pTagText))
{
// Set a few properties for the text object.
pTagText->setTag("Area"); // Always set the tag attribute.
pTagText->setPosition(AcGePoint3d(0.0,0.0,0.0));
pTagText->setHeight(0.5);
pTagText->setVerticalMode(AcDb::TextVertMode::kTextVertMid);
pTagText->setHorizontalMode(AcDb::TextHorzMode::kTextCenter);
// Set the value of the expression to display
// the area of the associated entity.
char* pszExpressionString = ".AREA";
// Store the expression with the annotation text object.
acErrStatus = SetExpressionString(kpszExpressionString, pTagText, kAttDefAnnotationString);
}
// Print the value of the expression that we just set.
char* pszOutExpression = NULL;
acErrStatus = GetExpressionString(pchOutExpression, pTagText, kAttDefAnnotationString);
if (acErrStatus == Acad::eOk)
{
acutPrintf("Tag = %s. Expression string = %s\n", pTagText->tag(), pchOutExpression);
acutDelString(pchOutExpression);
}
Inserting Annotation References
Call InsertAnnotationReference() to attach an annotation reference to a particular entity. Optionally, you can override the default property values of the base annotation template when you insert a new annotation reference: One form of InsertAnnotationReference() uses the property values of an existing annotation reference to set the values of the new reference, and the other form lets you specify an AnnotationOverrides struct of explicit override values. To attach an annotation reference to more than one entity, call InsertAnnotationReferences() (which also supports property overrides).
For annotation source-code samples, see Annotation Samples.
AcDbObjectId idNewBlkRefId; // Output object ID of the newly created annotation reference.
char* pszTemplateName = "MyAnnotationTemplate"; // Name of existing template.
AcDbObjectId idAssocEnt; // Object ID of entity to attach annotation to.
Acad::ErrorStatus acErrStatus;
// Draw a circle to associate the annotation with.
AcGePoint3d ptCenter(0,0,0);
AcGeVector3d vcNorm(0,0,1);
double dInRadius = 5.5;
idAssocEnt = DrawCircle(ptCenter, vcNorm, dInRadius);
// Attach the annotation reference to the circle.
// The annotation will appear in the current drawing
// if its annotation text expression(s) can be evaluated.
// The MyAnnotationTemplate text expression is set to .AREA.
acErrStatus = InsertAnnotationReference(idNewBlkRefId, pszTemplateName, idAssocEnt);
// Test to see if the insertion succeeded.
if(acErrStatus != Acad::eOk)
{
// Handle the error...
}
If an entity associated with an annotation reference changes, call RefreshAnnotationReferences() to refresh the annotation. If an annotation template changes, call UpdateAnnotationReferences() to update the annotation references based on that template. Both functions let you control how the annotation reference's property values are updated.
For annotation source-code samples, see Annotation Samples.
char* pszTemplateName = "MyAnnotationTemplate"; // Name of existing template.
bool bFullAnnotation;
bool bRetainLocal;
Acad::ErrorStatus acErrStatus;
bFullAnnotation = false; // Re-evaluate only the text string - don't change other properties.
acErrStatus = RefreshAnnotationReferences(pszTemplateName, bFullAnnotation);
bRetainLocal = true; // Don't discard the local property values.
acErrStatus = UpdateAnnotationReferences(pszTemplateName, bRetainLocal);
// Test to see if the update succeeded.
if(acErrStatus != Acad::eOk)
{
// Handle the error...
}
To delete an annotation template, call DeleteAnnotationTemplate(). You can delete only templates with no annotation references, which you can check with IsAnnotationTemplateReferenced().AnnotationTemplateReferencedObjIds() lists all of a template's references, which you must delete before you can delete the template. Delete an annotation reference in the same way that you would delete any AutoCAD object.
For annotation source-code samples, see Annotation Samples.
#include dbmain.h // Needed for acdbOpenObject().
char* pszTemplateName = "MyAnnotationTemplate"; // Template to delete.
Acad::ErrorStatus acErrStatus;
if(AnnotationTemplateExists(pszTemplateName))
{
// If the template has any annotation references, delete them.
if(IsAnnotationTemplateReferenced(pszTemplateName))
{
AcDbObjectIdArray arrOutIdObjs;
AcDbObject* pObj = NULL;
if((AnnotationTemplateReferencedObjIds(arrOutIdObjs, pszTemplateName)) == Acad::eOk)
{
// Open, erase, and close each returned object reference.
while(arrOutIdObjs.length( ))
{
acErrStatus = acdbOpenObject(pObj, arrOutIdObjs.first( ), AcDb::kForWrite);
if((acErrStatus == Acad::eOk) && (pObj))
{
pObj->erase( );
pObj->close( );
pObj = NULL;
// Remove the ID of the erased object.
arrOutIdObjs.removeFirst( );
}
else
{
// Handle the error...
}
if((DeleteAnnotationTemplate(pszTemplateName)) != Acad::eOk)
{
// Handle the error...
}
}
You can use several general functions to manage annotation templates and references.GetTemplateNames() lists the annotation templates defined in the current drawing. Autodesk Map stores an annotation template as a block (AcDbBlockTableRecord) and an annotation reference as a block reference (AcDbBlockReference).
IsAnnotationTemplate() determines whether an AcDbBlockTableRecord is an annotation template and AnnotationTemplateBlockDefinitionId() gets a template's AcDbBlockTableRecord.
IsAnnotationBlockReference() determines whether a AcDbBlockReference is an annotation reference;AnnotationBlockReferenceAssociatedObjectId() returns the ID of the object associated with a specific annotation reference; and TemplateNameBTRPrefix() returns the special prefix string ("ACMAP_ANN_TEMPLATE_") that Autodesk Map silently prepends to each annotation template name.
For annotation source-code samples, see Annotation Samples.
// Get all the annotation template names.
Acad::ErrorStatus acErrStatus;
AcArray<char*> acarrTemNameArray;
acErrStatus = GetTemplateNames(acarrTemNameArray);
if((acErrStatus == Acad::eOk) && (!(acarrTemNameArray.isEmpty( ))))
{
// Process the templates...
}
- For more information about annotation in AutoCAD Map 3D, choose Help > Autodesk Map Help > Contents tab (or press F1), and then navigate to Using AutoCAD Map 3D (by feature) > Annotation.
- For an annotation tutorial in AutoCAD Map 3D, choose Help > Tutorials > Contents tab, and then choose "Adding Annotations to Objects".
- For more information about expressions in AutoCAD Map 3D, choose Help > Autodesk Map Help > Contents tab (or press F1), and then navigate to Expression Evaluator.
To view code samples of annotation functions, open the Samples folder in your AutoCAD Map 3D ObjectARX installation and navigate to Map Samples\Annotation.