Annotation Templates

AutoCAD Map 3D .NET API

 
Annotation Templates
 
 
 

An annotation template is a special block in the drawing. It defines the fixed and variable parts of the annotation.

NoteFor more information about blocks, refer to the AutoCAD developer documentation.

Internally, annotation templates use a special naming convention. The names of all blocks containing annotation templates begin with ACMAP_ANN_TEMPLATE_. This prefix is defined in the Annotations.TemplateNameBlockTableRecordPrefix property.

Annotation API calls, though, use the annotation name as it appears in the UI. For example, an annotation template named ParcelName would be stored in a block named ACMAP_ANN_TEMPLATE_ParcelName, but it would be created with a call to Annotations.CreateAnnotationTemplate("ParcelName").

The ProjectModel.Annotations property returns an Annotations object that can be used for managing the annotations and annotation templates.

Attributes

An AutoCAD block can contain attribute definitions, which are text entities that can define informational text for each block reference.

In an annotation template, attribute definitions are used to define the variable parts of the annotation. For example, if the annotations include object data, then attribute definitions in the block template define what object data should appear and how it will be displayed.

The AttributeDefinition class inherits the DBText class, which inherits the Entity class. These have properties such as Color and Height that define how the annotation will appear in the drawing. For example, to set the text height for an annotation, set the Height property of the attribute definition used for the annotation.

NoteThe properties used for the attribute definition can also be modified using expression strings. See Expressions in Annotations for details.

Creating an Annotation Template

Although an annotation template is a form of AutoCAD block, it must be created using the Map API or it will not be recognized properly.

  • Start a transaction.
  • Create the annotation template using Annotations.CreateAnnotationTemplate().
  • Get a reference to the annotation template using Annotations.Item().
  • If required, set block properties for the annotation template using AnnotationTemplate.SetExpressionString(). For example, this can be used to rotate the block reference to match the rotation of the object being annotated.
  • If required, add fixed drawing objects to the annotation template. Get the AutoCAD block id using the AnnotationTemplate.BlockDefinitionId property and add drawing objects to the template using standard AutoCAD API calls.
  • Add variable annotation text to the template using AnnotationTemplate.CreateAnnotationText(). This creates an attribute definition in the block.
  • Set the display properties of the annotation text by setting properties for the attribute definition.
  • Set the expression string for the annotation text using Annotations.SetExpressionString().
  • Commit the transaction.

Annotations.CreateAnnotationTemplate() creates an empty template. It returns an AutoCAD ObjectID that is the id of the block table record. Get a reference to the annotation template object using Annotations.Item().

Dim annotations As Annotation.Annotations = _
   activeProj.Annotations
 
Dim trans As Transaction = Nothing
trans = activeDoc.TransactionManager.StartTransaction()
Dim newTemplateId As ObjectId = _
   annotations.CreateAnnotationTemplate("templateName")
 
Dim newTemplate As Annotation.AnnotationTemplate = _
   annotations(newTemplateId)

If required, set block properties for the annotation template. See Expressions in Annotations for details.

newTemplate.SetExpressionString(_
   Annotation.AnnotationExpressionFields.BlockRotation, ".ANGLE")

Add objects to the template. They can be normal drawing objects or annotation text.

To add normal drawing objects, use standard AutoCAD methods.

Dim line As New Line
line.StartPoint = New Geometry.Point3d(0.0, -0.6, 0.0)
line.EndPoint = New Geometry.Point3d(2.0, -0.6, 0.0)
Dim blockTableRec As BlockTableRecord
blockTableRec = newTemplateId.GetObject(OpenMode.ForWrite)
blockTableRec.AppendEntity(line)
trans.AddNewlyCreatedDBObject(line, True)

To add annotation text, create an annotation text object. This is a special type of AutoCAD attribute definition. AnnotationTemplate.CreateAnnotationText() returns the AutoCAD ObjectId of the attribute definition. Open this object for writing and cast to an AttributeDefinition object:

Dim expressionTextId As ObjectId
expressionTextId = newTemplate.CreateAnnotationText()
Dim attDef As AttributeDefinition
attDef = _
  CType(trans.GetObject(expressionTextId, OpenMode.ForWrite), _
  AttributeDefinition)

Most of the properties for the annotation template can be set using the AttributeDefinition properties. For example:

attDef.Position = _
  New Autodesk.AutoCAD.Geometry.Point3d(0.0, 0.0, 0.0)
attDef.Tag = "testTag"
attDef.Height = 0.5
attDef.VerticalMode = TextVerticalMode.TextVerticalMid
attDef.HorizontalMode = TextHorizontalMode.TextCenter
attDef.AlignmentPoint = 
  New Autodesk.AutoCAD.Geometry.Point3d(0.0, 0.0, 0.0)

The annotation text must be set using Annotations.SetExpressionString(). See Expressions in Annotations for details.