This document is archived and information here might be outdated.  Recommended version.


Creating annotation and dimension feature classes (ArcObjects .NET 10.8 SDK)
ArcObjects Help for .NET developers > ArcObjects Help for .NET developers > Developing with ArcGIS > Learning ArcObjects > Managing data > Working with feature data > Creating and modifying schema > Creating annotation and dimension feature classes

Creating annotation and dimension feature classes


Summary
This topic explains how to create annotation and dimension feature classes. Creating these classes is different than creating regular feature classes because annotation and dimension classes store additional information, such as symbol collections (in the case of annotation feature classes) and dimension styles (in the case of dimension feature classes).

In this topic

Working with annotation and dimension feature classes

Annotation and dimension classes are special types of feature classes that have additional properties and custom behavior. For more information on this behavior, see the ArcGIS Help topics What is annotation? and What are dimensions?.
For a developer creating these feature classes, there are some similarities between the two types of classes. Each is implemented as the following two-part solution: 
  • New types are defined for each of the class's instances.
  • Each has a class extension that implements additional behavior and manages stored properties.
The objects instantiated from the classes are not features (ESRI.ArcGIS.Geodatabase.Feature), but AnnotateFeature and DimensionFeature (both found in the ESRI.ArcGIS.Carto assembly and namespace). These classes extend Feature, overriding some of its behavior, and implementing additional functionality through IAnnotateFeature and IAnnotateFeature2 (for annotation features) and IDimensionFeature (for dimension features).
The required class extensions for annotation feature classes and dimension feature classes are AnnotationFeatureClassExtension (implements numerous annotation-specific interfaces) and DimensionFeatureClassExtension (primarily accessed through IDimensionClassExtension and IDimensionClassExtension2). Both store data, such as, symbol collections (for annotation feature classes) and dimension styles (for dimension feature classes) using extension properties; however, do not access the properties with IClass.ExtensionProperties, as both of the class extensions have members defined in their interfaces that provide a better way of accessing and modifying the properties. See the following code examples that include examples of these members.
This topic discusses the creation of standard annotation feature classes, but does not discuss the creation of feature-linked annotation feature classes. Typically, feature-linked annotation feature classes are created by converting labels with the ConvertLabelsToAnnotation class. For more information on how to use the ConvertLabelsToAnnotation class, see Converting labels to geodatabase annotation for an entire map and Converting labels to geodatabase annotation for a single layer.

Creating a standard annotation feature class

Creating a standard annotation feature class has little in common with creating a regular feature class. The IAnnotationLayerFactory interface - implemented by the FDOGraphicsLayerFactory class - should be used to generate a new annotation feature class. The CreateAnnotationLayer method of that interface requires the following parameters to create a class:
  • The workspace where the class is created.
  • The feature dataset that contains the class. Passing null to this parameter creates the class at the workspace level.
  • The class name.
  • An IGeometryDef reference for the class.
  • An associated feature class. For standard annotation feature classes, pass a null value into this parameter.
  • A collection of annotation layer properties as an IAnnotateLayerPropertiesCollection reference. Each member in the collection represents an annotation class, viewable in ArcCatalog through the annotation feature class's properties (at least one class is required).
  • An IGraphicsLayerScale reference. This allows the reference units and reference scale of the class to be set.
  • A symbol collection as an ISymbolCollection reference. Each member of the collection represents an annotation style within the class (at least one style is required).
  • Several Boolean values that determine the class's behavior.
  • An IOverposterProperties reference. In standard annotation feature classes, these are unused, but required when creating the annotation feature class.
  • A configuration keyword. This provides the same functionality that configuration keywords provide to methods, such as IFeatureWorkspace.CreateFeatureClass.
The process of acquiring several of the preceding parameters (such as, the target workspace) is similar to that of a regular feature class, and can be found in other topics. The following sections discuss how to create a collection of annotation layer properties, a graphics layer scale object, a symbol collection, and create the annotation feature class.
Annotation feature class and annotation class are not synonymous. Annotation feature class refers to the actual dataset in the geodatabase, whereas, annotation class refers to the different classes of annotation within the feature class. These can be viewed through the feature class's properties in ArcCatalog under the Annotation Classes tab.

Creating annotation classes and a symbol collection

Annotation feature classes contain one or more annotation classes. Each annotation class contains properties that determine how a subset of annotation in the feature class displays. If there is more than one annotation class in an annotation feature class, subtypes are also created for each annotation class.
When an annotation class is created, its symbol must be added to the symbol collection that is used to create the annotation feature class. The following code example shows how to create an annotation class, add its symbol to a new symbol collection, then add the class to a properties collection:
[C#] 
// Create an annotation class and provide it with a name.
ILabelEngineLayerProperties labelEngineLayerProperties=new
    LabelEngineLayerPropertiesClass();
IAnnotateLayerProperties annotateLayerProperties=(IAnnotateLayerProperties)
    labelEngineLayerProperties;
annotateLayerProperties.Class="Annotation Class 1";

// Get the symbol from the annotation class. Make any changes to its properties
// here.
ITextSymbol annotationTextSymbol=labelEngineLayerProperties.Symbol;
ISymbol annotationSymbol=(ISymbol)annotationTextSymbol;

// Create a symbol collection and add the default symbol from the
// annotation class to the collection. Assign the resulting symbol ID
// to the annotation class.
ISymbolCollection symbolCollection=new SymbolCollectionClass();
ISymbolCollection2 symbolCollection2=(ISymbolCollection2)symbolCollection;
ISymbolIdentifier2 symbolIdentifier2=null;
symbolCollection2.AddSymbol(annotationSymbol, "Annotation Class 1", out
    symbolIdentifier2);
labelEngineLayerProperties.SymbolID=symbolIdentifier2.ID;

// Add the annotation class to a collection.
IAnnotateLayerPropertiesCollection annotateLayerPropsCollection=new
    AnnotateLayerPropertiesCollectionClass();
annotateLayerPropsCollection.Add(annotateLayerProperties);
[VB.NET] 
' Create an annotation class and provide it with a name.
Dim labelEngineLayerProperties As ILabelEngineLayerProperties=New LabelEngineLayerPropertiesClass()
Dim annotateLayerProperties As IAnnotateLayerProperties=CType(labelEngineLayerProperties, IAnnotateLayerProperties)
annotateLayerProperties.Class="Annotation Class 1"

' Get the symbol from the annotation class. Make any changes to its properties here.
Dim annotationTextSymbol As ITextSymbol=labelEngineLayerProperties.Symbol
Dim annotationSymbol As ISymbol=CType(annotationTextSymbol, ISymbol)

' Create a symbol collection and add the default symbol from the
' annotation class to the collection. Assign the resulting symbol ID
' to the annotation class.
Dim symbolCollection As ISymbolCollection=New SymbolCollectionClass()
Dim symbolCollection2 As ISymbolCollection2=CType(symbolCollection, ISymbolCollection2)
Dim symbolIdentifier2 As ISymbolIdentifier2=Nothing
symbolCollection2.AddSymbol(annotationSymbol, "Annotation Class 1", symbolIdentifier2)
labelEngineLayerProperties.SymbolID=symbolIdentifier2.ID

' Add the annotation class to a collection.
Dim annotateLayerPropsCollection As IAnnotateLayerPropertiesCollection=New AnnotateLayerPropertiesCollectionClass()
annotateLayerPropsCollection.Add(annotateLayerProperties)

Creating a graphics layer scale

A graphics layer scale is used to set the reference scale of the annotation feature class. The IGraphicsLayerScale interface has two properties, ReferenceScale and Units. Set the units to the same units used by the feature class's spatial reference, except when the spatial reference is unknown (in which case, use the unit the scale is calculated from).
The following code example shows how to create a graphics layer scale (this example assumes the referenceScale and referenceScaleUnits variables are previously defined, and are of types double and esriUnits, respectively):
[C#] 
// Create a graphics layer scale object.
IGraphicsLayerScale graphicsLayerScale=new GraphicsLayerScaleClass();
graphicsLayerScale.ReferenceScale=referenceScale;
graphicsLayerScale.Units=referenceScaleUnits;
[VB.NET] 
' Create a graphics layer scale object.
Dim graphicsLayerScale As IGraphicsLayerScale=New GraphicsLayerScaleClass()
graphicsLayerScale.ReferenceScale=referenceScale
graphicsLayerScale.Units=referenceScaleUnits

Creating overposter properties

Overposter properties are the labeling properties for the feature class's label engine. With standard annotation feature classes, they are unused, but are required when creating the feature classes. See the following code example:
[C#] 
// Create the overposter properties for the standard label engine.
IOverposterProperties overposterProperties=new BasicOverposterPropertiesClass();
[VB.NET] 
' Create the overposter properties for the standard label engine.
Dim overposterProperties As IOverposterProperties=New BasicOverposterPropertiesClass()

Creating a GeometryDef

As with object classes and feature classes, the AnnotationFeatureClassDescription class can be used to simplify the creation of annotation feature classes. Unlike other feature class creation methods, however, IAnnotationLayerFactory.CreateAnnotationLayer does not accept a fields collection as an input parameter. Instead, the class description (along with the RequiredFields property) can be used to acquire a GeometryDef object, which CreateAnnotationLayer does require.
The following code example shows how to get a GeometryDef from an instance of the AnnotationFeatureClassDescription class and apply a spatial reference to it:
[C#] 
// Instantiate a class description object.
IObjectClassDescription ocDescription=new AnnotationFeatureClassDescriptionClass();
IFeatureClassDescription fcDescription=(IFeatureClassDescription)ocDescription;

// Get the shape field from the class description's required fields.
IFields requiredFields=ocDescription.RequiredFields;
int shapeFieldIndex=requiredFields.FindField(fcDescription.ShapeFieldName);
IField shapeField=requiredFields.get_Field(shapeFieldIndex);
IGeometryDef geometryDef=shapeField.GeometryDef;
IGeometryDefEdit geometryDefEdit=(IGeometryDefEdit)geometryDef;
geometryDefEdit.SpatialReference_2=spatialReference;
[VB.NET] 
' Instantiate a class description object.
Dim ocDescription As IObjectClassDescription=New AnnotationFeatureClassDescriptionClass()
Dim fcDescription As IFeatureClassDescription=CType(ocDescription, IFeatureClassDescription)

' Get the shape field from the class description's required fields.
Dim requiredFields As IFields=ocDescription.RequiredFields
Dim shapeFieldIndex As Integer=requiredFields.FindField(fcDescription.ShapeFieldName)
Dim shapeField As IField=requiredFields.Field(shapeFieldIndex)
Dim geometryDef As IGeometryDef=shapeField.GeometryDef
Dim geometryDefEdit As IGeometryDefEdit=CType(geometryDef, IGeometryDefEdit)
geometryDefEdit.SpatialReference_2=spatialReference

Using the annotation layer factory

The final step is to create an annotation layer factory and use it to create the annotation feature class. IAnnotationLayerFactory.CreateAnnotationLayer returns an IAnnotationLayer, which can be added to the current map in ArcMap or an ArcObjects mapping application.
In the following code example, the annotation feature class is retrieved from the annotation layer:
[C#] 
// Create the annotation layer factory.
IAnnotationLayerFactory annotationLayerFactory=new FDOGraphicsLayerFactoryClass();

// Create the annotation feature class and an annotation layer for it.
IAnnotationLayer annotationLayer=annotationLayerFactory.CreateAnnotationLayer
    (featureWorkspace, featureDataset, className, geometryDef, null,
    annotateLayerPropsCollection, graphicsLayerScale, symbolCollection, false, false,
    false, true, overposterProperties, configKeyword);

// Get the feature class from the feature layer.
IFeatureLayer featureLayer=(IFeatureLayer)annotationLayer;
IFeatureClass featureClass=featureLayer.FeatureClass;
[VB.NET] 
' Create the annotation layer factory.
Dim annotationLayerFactory As IAnnotationLayerFactory=New FDOGraphicsLayerFactoryClass()

' Create the annotation feature class and an annotation layer for it.
Dim annotationLayer As IAnnotationLayer=annotationLayerFactory.CreateAnnotationLayer(featureWorkspace, _
                                          featureDataset, className, geometryDef, Nothing, annotateLayerPropsCollection, graphicsLayerScale, _
                                          symbolCollection, False, False, False, True, overposterProperties, configKeyword)

' Get the feature class from the feature layer.
Dim featureLayer As IFeatureLayer=CType(annotationLayer, IFeatureLayer)
Dim featureClass As IFeatureClass=featureLayer.FeatureClass

Complete code example

The following code example combines the two preceding examples into a complete method:
[C#] 
public IFeatureClass CreateStandardAnnotationClass(IFeatureWorkspace
    featureWorkspace, IFeatureDataset featureDataset, String className,
    ISpatialReference spatialReference, int referenceScale, esriUnits
    referenceScaleUnits, String configKeyword)
{
    // Create an annotation class and provide it with a name.
    ILabelEngineLayerProperties labelEngineLayerProperties=new
        LabelEngineLayerPropertiesClass();
    IAnnotateLayerProperties annotateLayerProperties=(IAnnotateLayerProperties)
        labelEngineLayerProperties;
    annotateLayerProperties.Class="Annotation Class 1";

    // Get the symbol from the annotation class. Make any changes to its properties
    // here.
    ITextSymbol annotationTextSymbol=labelEngineLayerProperties.Symbol;
    ISymbol annotationSymbol=(ISymbol)annotationTextSymbol;

    // Create a symbol collection and add the default symbol from the
    // annotation class to the collection. Assign the resulting symbol ID
    // to the annotation class.
    ISymbolCollection symbolCollection=new SymbolCollectionClass();
    ISymbolCollection2 symbolCollection2=(ISymbolCollection2)symbolCollection;
    ISymbolIdentifier2 symbolIdentifier2=null;
    symbolCollection2.AddSymbol(annotationSymbol, "Annotation Class 1", out
        symbolIdentifier2);
    labelEngineLayerProperties.SymbolID=symbolIdentifier2.ID;

    // Add the annotation class to a collection.
    IAnnotateLayerPropertiesCollection annotateLayerPropsCollection=new
        AnnotateLayerPropertiesCollectionClass();
    annotateLayerPropsCollection.Add(annotateLayerProperties);

    // Create a graphics layer scale object.
    IGraphicsLayerScale graphicsLayerScale=new GraphicsLayerScaleClass();
    graphicsLayerScale.ReferenceScale=referenceScale;
    graphicsLayerScale.Units=referenceScaleUnits;

    // Create the overposter properties for the standard label engine.
    IOverposterProperties overposterProperties=new BasicOverposterPropertiesClass()
        ;

    // Instantiate a class description object.
    IObjectClassDescription ocDescription=new
        AnnotationFeatureClassDescriptionClass();
    IFeatureClassDescription fcDescription=(IFeatureClassDescription)ocDescription;

    // Get the shape field from the class description's required fields.
    IFields requiredFields=ocDescription.RequiredFields;
    int shapeFieldIndex=requiredFields.FindField(fcDescription.ShapeFieldName);
    IField shapeField=requiredFields.get_Field(shapeFieldIndex);
    IGeometryDef geometryDef=shapeField.GeometryDef;
    IGeometryDefEdit geometryDefEdit=(IGeometryDefEdit)geometryDef;
    geometryDefEdit.SpatialReference_2=spatialReference;

    // Create the annotation layer factory.
    IAnnotationLayerFactory annotationLayerFactory=new
        FDOGraphicsLayerFactoryClass();

    // Create the annotation feature class and an annotation layer for it.
    IAnnotationLayer annotationLayer=annotationLayerFactory.CreateAnnotationLayer
        (featureWorkspace, featureDataset, className, geometryDef, null,
        annotateLayerPropsCollection, graphicsLayerScale, symbolCollection, false,
        false, false, true, overposterProperties, configKeyword);

    // Get the feature class from the feature layer.
    IFeatureLayer featureLayer=(IFeatureLayer)annotationLayer;
    IFeatureClass featureClass=featureLayer.FeatureClass;

    return featureClass;
}
[VB.NET] 
Public Function CreateStandardAnnotationClass(ByVal featureWorkspace As IFeatureWorkspace, _
                                              ByVal featureDataset As IFeatureDataset, ByVal className As String, _
                                              ByVal spatialReference As ISpatialReference, ByVal referenceScale As Integer, _
                                              ByVal referenceScaleUnits As esriUnits, ByVal configKeyword As String) As IFeatureClass
    
    ' Create an annotation class and provide it with a name.
    Dim labelEngineLayerProperties As ILabelEngineLayerProperties=New LabelEngineLayerPropertiesClass()
    Dim annotateLayerProperties As IAnnotateLayerProperties=CType(labelEngineLayerProperties, IAnnotateLayerProperties)
    annotateLayerProperties.Class="Annotation Class 1"
    
    ' Get the symbol from the annotation class. Make any changes to its properties here.
    Dim annotationTextSymbol As ITextSymbol=labelEngineLayerProperties.Symbol
    Dim annotationSymbol As ISymbol=CType(annotationTextSymbol, ISymbol)
    
    ' Create a symbol collection and add the default symbol from the
    ' annotation class to the collection. Assign the resulting symbol ID
    ' to the annotation class.
    Dim symbolCollection As ISymbolCollection=New SymbolCollectionClass()
    Dim symbolCollection2 As ISymbolCollection2=CType(symbolCollection, ISymbolCollection2)
    Dim symbolIdentifier2 As ISymbolIdentifier2=Nothing
    symbolCollection2.AddSymbol(annotationSymbol, "Annotation Class 1", symbolIdentifier2)
    labelEngineLayerProperties.SymbolID=symbolIdentifier2.ID
    
    ' Add the annotation class to a collection.
    Dim annotateLayerPropsCollection As IAnnotateLayerPropertiesCollection=New AnnotateLayerPropertiesCollectionClass()
    annotateLayerPropsCollection.Add(annotateLayerProperties)
    
    ' Create a graphics layer scale object.
    Dim graphicsLayerScale As IGraphicsLayerScale=New GraphicsLayerScaleClass()
    graphicsLayerScale.ReferenceScale=referenceScale
    graphicsLayerScale.Units=referenceScaleUnits
    
    ' Create the overposter properties for the standard label engine.
    Dim overposterProperties As IOverposterProperties=New BasicOverposterPropertiesClass()
    
    ' Instantiate a class description object.
    Dim ocDescription As IObjectClassDescription=New AnnotationFeatureClassDescriptionClass()
    Dim fcDescription As IFeatureClassDescription=CType(ocDescription, IFeatureClassDescription)
    
    ' Get the shape field from the class description's required fields.
    Dim requiredFields As IFields=ocDescription.RequiredFields
    Dim shapeFieldIndex As Integer=requiredFields.FindField(fcDescription.ShapeFieldName)
    Dim shapeField As IField=requiredFields.Field(shapeFieldIndex)
    Dim geometryDef As IGeometryDef=shapeField.GeometryDef
    Dim geometryDefEdit As IGeometryDefEdit=CType(geometryDef, IGeometryDefEdit)
    geometryDefEdit.SpatialReference_2=spatialReference
    
    ' Create the annotation layer factory.
    Dim annotationLayerFactory As IAnnotationLayerFactory=New FDOGraphicsLayerFactoryClass()
    
    ' Create the annotation feature class and an annotation layer for it.
    Dim annotationLayer As IAnnotationLayer=annotationLayerFactory.CreateAnnotationLayer(featureWorkspace, _
                                              featureDataset, className, geometryDef, Nothing, annotateLayerPropsCollection, graphicsLayerScale, _
                                              symbolCollection, False, False, False, True, overposterProperties, configKeyword)
    
    ' Get the feature class from the feature layer.
    Dim featureLayer As IFeatureLayer=CType(annotationLayer, IFeatureLayer)
    Dim featureClass As IFeatureClass=featureLayer.FeatureClass
    
    Return featureClass
End Function

Creating a dimension feature class

Creating a dimension feature class is similar to creating a regular feature class, except with the following two main differences:
  • When calling IFeatureWorkspace.CreateFeatureClass or IFeatureDataset.CreateFeatureClass to create the class, several of the parameters are different from those used to create a simple feature class.
  • After the class is created, it is not immediately ready to be used. A dimension class extension maintains a collection of dimension styles. These are objects that describe the look and feel of a dimension feature when rendered. A dimension feature must use one of its class's available styles. When a dimension feature class extension is initially created, its styles collection is empty; however, to use properly, it must contain one or more styles.
The following are the creation-time parameters that differ between a simple feature class and a dimension feature class:
  • The Fields parameter. Dimension feature classes require several fields in addition to the ObjectID and shape fields required by simple feature classes.
  • The class identifier (CLSID) parameter, the globally unique identifier (GUID) of the type used to instantiate the class's objects. For dimension feature classes, the GUID of DimensionFeature must be provided.
  • The extension class ID (EXTCLSID) parameter, the GUID of the class extension. For dimension feature classes, the GUID of DimensionFeatureClassExtension must be provided.
  • The FeatureType parameter that takes a value from the esriFeatureType enumeration to define the type of features the class stores. Simple feature classes use esriFTSimple, but dimension feature classes require esriFTDimension.
Fortunately, the DimensionClassDescription class (implementing the IObjectClassDescription and IFeatureClassDescription interfaces) provides a shortcut for obtaining the objects for three out of four parameters, with the fourth being trivial. After creating an instance of DimensionClassDescription and casting it to the IObjectClassDescription interface, the RequiredFields, InstanceCLSID, and ClassExtensionCLSID properties provide the necessary fields collection and the two GUIDs. The IFeatureClassDescription interface is required to get the ShapeFieldName parameter.
For more information about creating feature classes, see Creating feature classes.
The following code example shows how to use a dimension class description object to create a dimension feature class. At this point, the dimension feature class is not ready to be used. It must first be provided with one or more dimension styles.
[C#] 
// Create a DimensionClassDescription for the required fields and GUIDs.
IObjectClassDescription ocDescription=new DimensionClassDescriptionClass();

// By default, a dimension feature class has an unknown spatial reference. Modify the
// default GeometryDef from the RequiredFields to apply a spatial reference.
IFields requiredFields=ocDescription.RequiredFields;
int shapeFieldPosition=requiredFields.FindField("Shape");
IField shapeField=requiredFields.get_Field(shapeFieldPosition);
IGeometryDef geometryDef=shapeField.GeometryDef;
IGeometryDefEdit geometryDefEdit=(IGeometryDefEdit)geometryDef;
geometryDefEdit.SpatialReference_2=spatialReference;

// Any additional fields required by the dimension class should be added to the fields
// collection at this point.

// Create the feature class. Following this step, the dimension class is not ready to
// be used, as it contains no dimension styles.
IFeatureClass dimensionFeatureClass=featureWorkspace.CreateFeatureClass(className,
    requiredFields, ocDescription.InstanceCLSID, ocDescription.ClassExtensionCLSID,
    esriFeatureType.esriFTDimension, "Shape", "");
[VB.NET] 
' Create a DimensionClassDescription for the required fields and GUIDs.
Dim ocDescription As IObjectClassDescription=New DimensionClassDescription()

' By default, a dimension feature class has an unknown spatial reference. Modify the
' default GeometryDef from the RequiredFields to apply a spatial reference.
Dim requiredFields As IFields=ocDescription.RequiredFields
Dim shapeFieldPosition As Integer=requiredFields.FindField("Shape")
Dim shapeField As IField=requiredFields.Field(shapeFieldPosition)
Dim geometryDef As IGeometryDef=shapeField.GeometryDef
Dim geometryDefEdit As IGeometryDefEdit=CType(geometryDef, IGeometryDefEdit)
geometryDefEdit.SpatialReference_2=spatialReference

' Any additional fields required by the dimension class should be added to the fields
' collection at this point.
' Create the feature class. Following this step, the dimension class is not ready to
' be used, as it contains no dimension styles.
Dim dimensionFeatureClass As IFeatureClass=featureWorkspace.CreateFeatureClass(className, _
                                             requiredFields, ocDescription.InstanceCLSID, ocDescription.ClassExtensionCLSID, _
                                             esriFeatureType.esriFTDimension, "Shape", "")

Setting extension properties and creating dimension styles

The IDimensionClassExtension interface defines two properties that should be set before using the dimension feature class, ReferenceScale and ReferenceScaleUnits. A dimension class's reference scale units should be the same as the units used by the class's spatial reference, except when the spatial reference is unknown (in which case, use the unit that the scale is calculated from).
With the feature class created, add one or more styles to the class extension's styles collection, which is empty at this point. This section shows how to create a dimension style and add it to the extension's styles collection; however, an alternative is to take one or more styles from an existing dimension class and copy them to the new class. See the following illustration:
The DimensionStyle class implements properties that determine a style's appearance via the following interfaces:
  • IDimensionStyle - Use the Name property to give the style a human-readable name within the style collection. While not required (and not used while rendering a dimension feature), it is strongly recommended that this property be set. The interface's other property, ID, cannot be set, but is automatically generated when the style is added to a styles collection.
  • IDimensionStyleText - This interface exposes several properties that control how text associated with dimension features using the style appears. For the most part, this involves how the text is positioned in relation to the feature; however, properties such as TextSymbol allow the font, color, and size of the text to also be set.
  • IDimensionStyleDisplay - The properties of this interface determine how a dimension feature is rendered. While some properties are set on a feature-by-feature basis (such as the angle of the text), the properties set with this interface apply to all features that use the style (for example, the line symbols used while rendering).
Dimension styles are stored as extension properties; therefore, adding or deleting them is considered a schema change, and an exclusive lock on the class should be acquired using the ISchemaLock interface before doing so. After styles have been added or removed from the styles collection, call IDimensionClassExtension.UpdateProperties to persist the changes.
The following code example shows how to set the extension properties, create a simple dimension style, then add it to the extension:
[C#] 
// Acquire an exclusive schema lock. This is necessary because the class extension's
// properties will be modified, and it is possible that other processes could open the
// feature class.
ISchemaLock schemaLock=(ISchemaLock)dimensionFeatureClass;
try
{
    // Get an exclusive schema lock.
    schemaLock.ChangeSchemaLock(esriSchemaLock.esriExclusiveSchemaLock);

    // Get a reference to the dimension class extension and set the extension's reference
    // scale and reference scale units. The units should be the same as those used by the
    // class's spatial reference, unless the spatial reference is unknown (in which case,
    // the units should be set to those the scale is calculated from).
    IDimensionClassExtension dimensionClassExtension=(IDimensionClassExtension)
        dimensionFeatureClass.Extension;
    dimensionClassExtension.ReferenceScale=referenceScale;
    dimensionClassExtension.ReferenceScaleUnits=referenceScaleUnits;

    // Create a default dimension style and add it to the extension's collection of dimension
    // styles (which is empty at this point). Any modifications to the style should be made at
    // this point and any additional styles should also be added here.
    IDimensionStyle dimensionStyle=new DimensionStyleClass();
    dimensionStyle.Name="Default";
    IDimensionStyles dimensionStyles=dimensionClassExtension.DimensionStyles;
    dimensionStyles.AddStyle(dimensionStyle);

    // Update the class extension properties.
    dimensionClassExtension.UpdateProperties();

    return dimensionFeatureClass;
}

catch (COMException comExc)
{
    // Either the lock could not be acquired or the properties could not be updated.
    // In either case, the class is not fully prepared and should not be used.
    return null;
}

finally
{
    // Demote the exclusive lock to a shared lock.
    schemaLock.ChangeSchemaLock(esriSchemaLock.esriSharedSchemaLock);
}
[VB.NET] 
Dim schemaLock As ISchemaLock=CType(dimensionFeatureClass, ISchemaLock)
Try
' Get an exclusive schema lock.
schemaLock.ChangeSchemaLock(esriSchemaLock.esriExclusiveSchemaLock)

' Get a reference to the dimension class extension and set the extension's reference
' scale and reference scale units. The units should be the same as those used by the
' class's spatial reference, unless the spatial reference is unknown (in which case,
' the units should be set to those the scale is calculated from).
Dim dimensionClassExtension As IDimensionClassExtension=CType(dimensionFeatureClass.Extension, IDimensionClassExtension)
dimensionClassExtension.ReferenceScale=referenceScale
dimensionClassExtension.ReferenceScaleUnits=referenceScaleUnits

' Create a default dimension style and add it to the extension's collection of dimension
' styles (which is empty at this point). Any modifications to the style should be made at
' this point and any additional styles should also be added here.
Dim dimensionStyle As IDimensionStyle=New DimensionStyleClass()
dimensionStyle.Name="Default"
Dim dimensionStyles As IDimensionStyles=dimensionClassExtension.DimensionStyles
dimensionStyles.AddStyle(dimensionStyle)

' Update the class extension properties.
dimensionClassExtension.UpdateProperties()
Return dimensionFeatureClass
Catch comExc As COMException
' Either the lock could not be acquired or the properties could not be updated.
' In either case, the class is not fully prepared and should not be used.
Return Nothing
Finally
' Demote the exclusive lock to a shared lock.
schemaLock.ChangeSchemaLock(esriSchemaLock.esriSharedSchemaLock)
End Try

Complete code example

The following code example combines the two preceding examples into a complete method:
[C#] 
public IFeatureClass CreateDimensionClass(IFeatureWorkspace featureWorkspace, String
    className, ISpatialReference spatialReference, Double referenceScale, esriUnits
    referenceScaleUnits)
{
    // Create a DimensionClassDescription for the required fields and GUIDs.
    IObjectClassDescription ocDescription=new DimensionClassDescriptionClass();

    // By default, a dimension feature class has an unknown spatial reference. Modify the
    // default GeometryDef from the RequiredFields to apply a spatial reference.
    IFields requiredFields=ocDescription.RequiredFields;
    int shapeFieldPosition=requiredFields.FindField("Shape");
    IField shapeField=requiredFields.get_Field(shapeFieldPosition);
    IGeometryDef geometryDef=shapeField.GeometryDef;
    IGeometryDefEdit geometryDefEdit=(IGeometryDefEdit)geometryDef;
    geometryDefEdit.SpatialReference_2=spatialReference;

    // Any additional fields required by the dimension class should be added to the fields
    // collection at this point.
    // Create the feature class. Following this step, the dimension class is not ready to
    // be used, as it contains no dimension styles.
    IFeatureClass dimensionFeatureClass=featureWorkspace.CreateFeatureClass
        (className, requiredFields, ocDescription.InstanceCLSID,
        ocDescription.ClassExtensionCLSID, esriFeatureType.esriFTDimension, "Shape",
        "");

    // Acquire an exclusive schema lock. This is necessary because the class extension's
    // properties will be modified, and it is possible that other processes could open the
    // feature class.
    ISchemaLock schemaLock=(ISchemaLock)dimensionFeatureClass;
    try
    {
        // Get an exclusive schema lock.
        schemaLock.ChangeSchemaLock(esriSchemaLock.esriExclusiveSchemaLock);

        // Get a reference to the dimension class extension and set the extension's reference
        // scale and reference scale units. The units should be the same as those used by the
        // class's spatial reference, unless the spatial reference is unknown (in which case,
        // the units should be set to those the scale is calculated from).
        IDimensionClassExtension dimensionClassExtension=(IDimensionClassExtension)
            dimensionFeatureClass.Extension;
        dimensionClassExtension.ReferenceScale=referenceScale;
        dimensionClassExtension.ReferenceScaleUnits=referenceScaleUnits;

        // Create a default dimension style and add it to the extension's collection of dimension
        // styles (which is empty at this point). Any modifications to the style should be made at
        // this point and any additional styles should also be added here.
        IDimensionStyle dimensionStyle=new DimensionStyleClass();
        dimensionStyle.Name="Default";
        IDimensionStyles dimensionStyles=dimensionClassExtension.DimensionStyles;
        dimensionStyles.AddStyle(dimensionStyle);

        // Update the class extension properties.
        dimensionClassExtension.UpdateProperties();

        return dimensionFeatureClass;
    }
    catch (COMException comExc)
    {
        // Either the lock could not be acquired or the properties could not be updated.
        // In either case, the class is not fully prepared and should not be used.
        return null;
    }
    finally
    {
        // Demote the exclusive lock to a shared lock.
        schemaLock.ChangeSchemaLock(esriSchemaLock.esriSharedSchemaLock);
    }
}
[VB.NET] 
Public Function CreateDimensionClass(ByVal featureWorkspace As IFeatureWorkspace, ByVal className As String, _
                                     ByVal spatialReference As ISpatialReference, ByVal referenceScale As Double, ByVal referenceScaleUnits As esriUnits) _
                                     As IFeatureClass
    
    ' Create a DimensionClassDescription for the required fields and GUIDs.
    Dim ocDescription As IObjectClassDescription=New DimensionClassDescription()
    
    ' By default, a dimension feature class has an unknown spatial reference. Modify the
    ' default GeometryDef from the RequiredFields to apply a spatial reference.
    Dim requiredFields As IFields=ocDescription.RequiredFields
    Dim shapeFieldPosition As Integer=requiredFields.FindField("Shape")
    Dim shapeField As IField=requiredFields.Field(shapeFieldPosition)
    Dim geometryDef As IGeometryDef=shapeField.GeometryDef
    Dim geometryDefEdit As IGeometryDefEdit=CType(geometryDef, IGeometryDefEdit)
    geometryDefEdit.SpatialReference_2=spatialReference
    
    ' Any additional fields required by the dimension class should be added to the fields
    ' collection at this point.
    
    ' Create the feature class. Following this step, the dimension class is not ready to
    ' be used, as it contains no dimension styles.
    Dim dimensionFeatureClass As IFeatureClass=featureWorkspace.CreateFeatureClass(className, _
                                                 requiredFields, ocDescription.InstanceCLSID, ocDescription.ClassExtensionCLSID, _
                                                 esriFeatureType.esriFTDimension, "Shape", "")
    
    ' Acquire an exclusive schema lock. This is necessary because the class extension's
    ' properties will be modified, and it is possible that other processes could open the
    ' feature class.
    Dim schemaLock As ISchemaLock=CType(dimensionFeatureClass, ISchemaLock)
    Try
    ' Get an exclusive schema lock.
    schemaLock.ChangeSchemaLock(esriSchemaLock.esriExclusiveSchemaLock)
    
    ' Get a reference to the dimension class extension and set the extension's reference
    ' scale and reference scale units. The units should be the same as those used by the
    ' class's spatial reference, unless the spatial reference is unknown (in which case,
    ' the units should be set to those the scale is calculated from).
    Dim dimensionClassExtension As IDimensionClassExtension=CType(dimensionFeatureClass.Extension, IDimensionClassExtension)
    dimensionClassExtension.ReferenceScale=referenceScale
    dimensionClassExtension.ReferenceScaleUnits=referenceScaleUnits
    
    ' Create a default dimension style and add it to the extension's collection of dimension
    ' styles (which is empty at this point). Any modifications to the style should be made at
    ' this point and any additional styles should also be added here.
    Dim dimensionStyle As IDimensionStyle=New DimensionStyleClass()
    dimensionStyle.Name="Default"
    Dim dimensionStyles As IDimensionStyles=dimensionClassExtension.DimensionStyles
    dimensionStyles.AddStyle(dimensionStyle)
    
    ' Update the class extension properties.
    dimensionClassExtension.UpdateProperties()
    
    Return dimensionFeatureClass
    Catch comExc As COMException
    ' Either the lock could not be acquired or the properties could not be updated.
    ' In either case, the class is not fully prepared and should not be used.
    Return Nothing
    Finally
    ' Demote the exclusive lock to a shared lock.
    schemaLock.ChangeSchemaLock(esriSchemaLock.esriSharedSchemaLock)
    End Try
End Function


See Also:

Creating feature classes
Converting labels to geodatabase annotation for an entire map
Converting labels to geodatabase annotation for a single layer



To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
ArcGIS Desktop Standard ArcGIS Desktop Standard
ArcGIS Desktop Advanced ArcGIS Desktop Advanced