Extending ArcObjects

Private Property Let IInfoElement_ShowAuthor(ByVal RHS As Boolean)
  m_bShowInfo(3) = RHS
End Property

Private Function GetAutoText() As String
  Dim sTemp As String
  If m_bShowInfo(0) Then
    sTemp = "User: " & m_sUser
    GetAutoText = GetAutoText & vbNewLine & sTemp
  End If
  ...

Private m_pApplication As esriFramework.IApplication

Friend Property Get EnableAppOptions() As Boolean
  EnableAppOptions = Not (m_pApplication Is Nothing)
End Property

Private Property Let IElement_Geometry(ByVal pGeometry As esriGeometry.IGeometry)
  If TypeOf pGeometry Is esriGeometryType.esriGeometryPoint Then
    Set m_pGeometry = CloneMe(pGeometry)
  End If
End Property

Private m_pSelectionTracker As esriDisplay.ISelectionTracker
...
Private Sub Class_Initialize()
  Set m_pSelectionTracker = New PolygonTracker
  m_pSelectionTracker.Locked = False
  m_pSelectionTracker.ShowHandles = False
  ...

Private Property Get IElement_SelectionTracker() As esriDisplay.ISelectionTracker
  Set IElement_SelectionTracker = m_pSelectionTracker
End Property

Private Sub RefreshTracker()
  If m_pCachedDisplay Is Nothing Then Exit Sub
  
  Set m_pSelectionTracker.Display = m_pCachedDisplay
  Dim pOutline As esriGeometry.IGeometry
  Set pOutline = New esriGeometry.Polygon
  IElement_QueryOutline m_pCachedDisplay, pOutline
  m_pSelectionTracker.Geometry = pOutline
End Sub

Private Sub IElement_Activate(ByVal Display As esriDisplay.IDisplay)
  Set m_pCachedDisplay = Display
  RefreshTracker
End Sub

Private Sub IElement_Deactivate()
  Set m_pCachedDisplay = Nothing
End Sub

Private Sub IElement_Draw(ByVal Display As esriDisplay.IDisplay, _
 ByVal TrackCancel As esriSystem.ITrackCancel)
  Display.SetSymbol Nothing
  Display.SetSymbol m_pTextSym
  Display.DrawText m_pPointGeometry, m_sAutoText
End Sub

Outline.SetEmpty
m_pTextSym.Text = GetAutoText
Dim pTransform As esriDisplay.IDisplayTransformation
Set pTransform = Display.DisplayTransformation

Dim pSym As esriDisplay.ISymbol
Set pSym = m_pTextSym
pSym.QueryBoundary frmResource.hDC, pTransform, m_pGeometry, Outline

Use ISymbol::QueryBoundary method to calculate the outline of an element.

You can make use of the QueryOutline method when you complete the QueryBounds method—call QueryOutline, and populate the Bounds parameter by using the IGeometry::QueryEnvelope method.

Private Sub IElement_QueryBounds(ByVal Display As esriDisplay.IDisplay, _
  ByVal Bounds As esriGeometry.IEnvelope)
  Dim pOutline As esriGeometry.IGeometry
  Set pOutline = New esriGeometry.Polygon
  IElement_QueryOutline m_pCachedDisplay, pOutline
  pOutline.QueryEnvelope Bounds
End Sub

It is worth noting that in many cases, QueryBounds is used by clients as an alternative to QueryOutline. For many elements, QueryBounds gives a rougher approximation of the shape of an element and is correspondingly more efficient to call. If a custom element has a QueryOutline method, which may be time-consuming (especially if called frequently in a loop), consider creating a more efficient QueryBounds method if an approximation can be easily calculated.

If possible, consider coding QueryBounds as a faster, rougher approximation of the same of an element than QueryOutline. You may find it useful to use Windows API calls to quickly approximate the extent of a piece of text.

You can also make use of the QueryOutline method when coding the HitTest method. First, create a Point object from the x and y coordinates passed in. Then retrieve the outline of the element, and use the IRelationalOperator's Disjoint method to find out if the Point lies inside the outline.

Private Function IElement_HitTest(ByVal X As Double, ByVal Y As Double, _
 ByVal Tolerance As Double) As Boolean
  Dim pPt As esriGeometry.IPoint
  Set pPt = New esriGeometry.Point
  pPt.PutCoords X, Y
  
  Dim pOutline As esriGeometry.IRelationalOperator
  Set pOutline = New esriGeometry.Polygon
  IElement_QueryOutline m_pCachedDisplay, pOutline
  IElement_HitTest = Not pOutline.Disjoint(pPt)
End Function

ArcMap determines if a user is trying to select a particular element by calling the HitText method to see if the mouse coordinates lie inside the outline of the element.

The Locked property was designed for use with graphic elements that are stored in a read-only geodatabase, and therefore, the InfoTextElement ignores the value passed to Locked.

Annotation elements (elements that implement IAnnotationElement) can implement the Locked property by retrieving the Feature associated with the annotation element, and checking the associated Workspace—if the workspace is currently being edited, then Locked should return false, and the Geometry of the element should be updatable.

Implementing IGraphicElement

Implementing IGraphicElement allows an element to appear in a dataframe, as it can account correctly for the coordinate system of the dataframe. Features store their Geometry and SpatialReference independently and are reprojected on-the-fly when drawn to a dataframe that has a different SpatialReference; however, elements are assumed to be in the same SpatialReference as the view in which they are displayed.

IGraphicElement allows an element to be projected to any coordinate system. It provides correct behavior for an element in the data view.

When the SpatialReference property is set, project the Geometry to the new SpatialReference; there is no need to check if the two SpatialReference values are equal, as Project will perform this check internally. Note that the SpatialReference property of an Element is held separately to the SpatialReference of the Element's Geometry, in the member variable m_pNativeSpatialRef.

Private m_pNativeSpatialRef As esriGeometry.ISpatialReference
...
Private Property Set IGraphicElement_SpatialReference(ByVal _
 SpatialReference As esriGeometry.ISpatialReference)
  ' pSpatialReference may  be null
  Set m_pNativeSpatialRef = SpatialReference
  UpdateElementSpatialReference
End Property

An element's Geometry should always have a SpatialReference the same as the current DisplayTransformation.

Now add the UpdateElementSpatialRef routine to perform the projection.

Private Sub UpdateElementSpatialReference()
  If Not m_pNativeSpatialRef Is Nothing Then
    If Not m_pPointGeometry Is Nothing Then
    
      If m_pPointGeometry.SpatialReference Is Nothing Then
        Set m_pPointGeometry.SpatialReference = _
        m_pCachedDisplay.DisplayTransformation.SpatialReference
      End If
      m_pPointGeometry.Project m_pNativeSpatialRef

      RefreshTracker
    End If
  End If
End Sub

The SpatialReference of an element may not be set on the first call to this property—in this case, you can use the SpatialReference of the cached Display as the initial native spatial reference of the Element.

The SpatialReference property of an element may not always be set before it is used—your code needs to account for this.

Implementing IElementProperties

All elements, frames, and graphics implement the IElementProperties interface; it provides functionality generally used by developers to identify elements and store custom properties on the element.

IElementProperties mainly provides ways for a programmer to add different types of information to an element. However, the AutoTransform property is used by the ITransform2D interface.

For the Name, Type and CustomProperty members, you should store and return data as required. For the Name property, simply allow a user to store a string. To be consistent with existing elements, this property is null by default. From the Type property return a string indicating the class of element—by default return "InfoTextElement". CustomProperty should hold an empty variant by default.

AutoTransform indicates which aspects of the element should be affected by using the ITransform2D interface. If AutoTransform is False, a transformation should only affect the Geometry of an element; if True, an element should also transform its Symbol or other properties as appropriate. For the AutoTransform property, simply return or store a boolean value—you will use it later when implementing ITransform2D.

Private Property Let IElementProperties_AutoTransform(ByVal AutoTransform _
 As Boolean)
  m_bAutoTrans = AutoTransform
End Property

Implementing IElementProperties2

IElementProperties2 should always be implemented on a custom Element—newer commands and tools may use this interface. This interface duplicates all the members of IElementProperties and adds two new ones. Return True from CanRotate, because text can be rotated to any angle, by setting the ITextSymbol::Angle property.

IElementProperties2 replicates the members of IElementProperties, and adds properties to determine how an element's Symbol is treated.

For the ReferenceScale property, return or store a double value indicating the reference scale—this value will be accounted for by the DisplayTransformation.

Private m_dRefScale As Double

Implementing IBoundsProperties

IBoundsProperties is used to determine how an element can be scaled. Return True from the read-only FixedSize property indicates that the InfoTextElement is an element whose size is determined not by its Geometry, but by its Symbol.

Private Property Get IBoundsProperties_FixedSize() As Boolean
  IBoundsProperties_FixedSize = True
End Property

You should also return True from the FixedAspectRatio property (and ignore any attempts to set the property), because if an element has a fixed size, its aspect ratio must also be fixed.

If FixedSize returns False, the Fixed Aspect Ratio check box on the Size and Position property page will be enabled; if FixedAspectRatio is True, the check box will be checked. The property page will calculate size and position changes based on these settings.

The Fixed Aspect Ratio check box on the Size and Position property page uses the IBoundsProperties interface to determine its availability and value.

Implementing ITransform2D

The Size and Position property page uses an element's ITransform2D interface to change an element; ITransform2D is also used in the element's context menu by the Nudge, Rotate and Flip, Align, and Distribute context-menu commands.

The ITransform2D interface allows an element to be moved, rotated, and scaled. The Size and Position property page uses the ITransform2D::Transform method to change height, width, and origin of an element. The other ITransform2D members are used by other ArcMap commands and tools.

For the Move and MoveVector methods you can simply forward the call to the ITransform2D interface of the element's Geometry and refresh the tracker after the transformation.

Private Sub ITransform2D_Move(ByVal dx As Double, ByVal dy As Double)
  Dim pTransform2D As esriGeometry.ITransform2D
  Set pTransform2D = m_pPointGeometry
  pTransform2D.Move dx, dy
  RefreshTracker
End Sub

As the InfoTextElement has a Point Geometry, rotation of the Element will not affect the orientation of the text itself; therefore, you should also check the value of the AutoTransform property you stored when implementing IElementProperties.

Private Sub ITransform2D_Rotate(ByVal Origin As esriGeometry.IPoint, _
 ByVal RotationAngle As Double)
  Dim pTransform2D As esriGeometry.ITransform2D
  Set pTransform2D = m_pPointGeometry
  pTransform2D.Rotate Origin, RotationAngle
  
  If m_bAutoTrans Then
    m_pTextSym.Angle = NewRotateAngle(RotationAngle)
  End If
  RefreshTracker
End Sub

If AutoTransform is True then the Symbol should also be rotated—set the Angle of the TextSymbol by adding the new rotation value to the existing Angle.

Private Function NewRotateAngle(ByVal dAngle As Double) As Double
  NewRotateAngle = m_pTextSym.Angle + RAD2DEG(dAngle)
End Function
  
Private Function RAD2DEG(ByVal Radians As Double) As Double
  RAD2DEG = Radians * (180# / PI)
End Function

ITransform2D methods should check the value of the AutoTranform property—if True, the element's Symbol needs to be transformed as well as the element's Geometry.

You can complete the Scale and Transform methods in a similar manner by first transforming the Geometry and accounting for the AutoTransform value. Note that the Scale method cannot scale both height and width, as the InfoTextElement has a fixed aspect ratio.

Private Sub ITransform2D_Scale(ByVal Origin As esriGeometry.IPoint, _
 ByVal sx As Double, ByVal sy As Double)
  
  Dim pTransform2D As esriGeometry.ITransform2D
  Set pTransform2D = m_pPointGeometry
  With pTransform2D
    .Scale Origin, sx, sy
  End With
  If m_bAutoTrans Then
    If sy <> 1 Then
      m_pTextSym.Size = m_pTextSym.Size * sy
    ElseIf sx <> 1 Then
      m_pTextSym.Size = m_pTextSym.Size * sx
    End If
  End If
  
  RefreshTracker
End Sub

The Transform method needs to account for translation, scaling, and rotation.

Implementing ITransformEvents

The majority of elements determine not only their location but their size and shape by their Geometry. Text-based elements are different—the location is determined by the Geometry, but the shape and size are determined by the current TextSymbol. This results in unexpected behavior for the SelectionTracker of a text-based element when the map scale is changed, as the SelectionTracker after the scale change will have a Geometry that is incorrect for the new map scale.

To correct this behavior, you can process the BoundsUpdated event of the current DisplayTransformation.

By sinking the outbound ITransformEvents interface of the DisplayTransformation, you can update your element to reflect changes such as the dataframe being rotated. You can also use ITransformEvents to update the tracker geometry correctly when the map scale changes.

Add a member variable to store the default outbound interface of DisplayTransformation, ITransformEvents.

Private WithEvents m_pDisplayTrans As DisplayTransformation

Now hook up this variable to the DisplayTransformation in Activate.

Private Sub IElement_Activate(ByVal Display As esriDisplay.IDisplay)
  Set m_pCachedDisplay = Display
  Set m_pDisplayTrans = Display.DisplayTransformation
  RefreshTracker
End Sub

Now refresh the tracker in the BoundsUpdate event.

Private Sub m_pDisplayTrans_BoundsUpdated(ByVal sender As _
 esriDisplay.IDisplayTransformation)
  RefreshTracker
End Sub

Implementing IClone, IPersistStream, and IPersistVariant

Cloning and persistence functionality are essential for any element. Your InfoTextElement should, therefore, implement IClone. If you are working in VC++, you should also implement IPersist and IPersistStream; if working in VB, implement IPersistVariant.

Elements must be clonable and persistable. See Chapter 2, 'Developing Objects', for general information on coding cloning and persistence methods.

In the Save persistence method, don't forget to update the document path, as saving the document may change this value. There is no need to persist the references to the current Application, SelectionTracker, or cached Display, as these will be set when the Element is re-created.

Private Sub IPersistVariant_Save(ByVal Stream As esriSystem.IVariantStream)
  m_sDocPath = GetDocPathString
  m_pTextSym.Text = GetAutoText
  
  Stream.Write m_lCurrVers
  Stream.Write m_pPointGeometry
  Stream.Write m_sElementName
  Stream.Write m_sElementType
  Stream.Write m_dRefScale
  Stream.Write m_pNativeSpatialRef
  Stream.Write m_pTextSym
  Stream.Write m_bShowInfo(0)
  ...
End Sub

You may also want to persist the IElementProperties CustomProperty method, in which case you would need to check if the set variant contains a persistable data type.

Plugging your custom element into ArcMap

Your custom element class is now ready to be used programmatically. However, to improve the usability of the element, there are two more issues you should consider. Using the ArcMap user interface, users should be able to create your element, add it to a document, and edit the properties of the element.

Creating a new InfoTextElement in ArcMap

If you are working in data view, you can add standard graphic elements to a document by selecting the appropriate shape from the Drawing Tools button on the Drawing toolbar, then tracking the element's shape onto the view as required. Alternatively, to add text or callouts, use the Text Tools button.

Elements are created in ArcMap by using either the Drawing Tools or Text Tools tool on the Drawing toolbar.

If you are working in layout view, you can again use the drawing toolbar to add graphic elements, or use the Insert menu to add other types of elements such as a Neatline (FrameElement).

These commands and tools are hardcoded to create each type of graphic or frame element—there is no component category that contains elements. You must, therefore, create a new command or tool to add a custom element to the ActiveView.

As the InfoTextElement is a graphic element, you will create a new tool that allows users to click on the ActiveView at the point they want to place an InfoTextElement. This behavior is similar to that used by the New Text tool.

Creating the NewInfoTextTool

Add a new class to your project called NewInfoTextTool and implement the ICommand and ITool interfaces in that class. In the ICommand::OnCreate method, store a reference to the Application.

Private m_pApp As esriFramework.IApplication
...
Private Sub ICommand_OnCreate(ByVal Hook As Object)
  Set m_pApp = Hook
End Sub

You should perform the majority of the work for this tool in the ITool::OnMouseDown method. If the left button has been clicked, create a Point in Map units. Set the Point's SpatialReference property to that of the Map.

If Button = 1 Then
  Dim pPoint As esriGeometry.IPoint, pMxApp As esriArcMapUI.IMxApplication
  Set pMxApp = m_pApp
  Set pPoint = pMxApp.Display.DisplayTransformation.ToMapPoint(X, Y)
  
  Dim pMxDoc As esriArcMapUI.IMxDocument, pMap As esriCarto.IMap
  Set pMxDoc = m_pApp.Document
  Set pMap = pMxDoc.ActiveView.FocusMap
  Set pPoint.SpatialReference = pMap.SpatialReference

Create a new InfoTextElement in the tool's OnMouseDown method. This can be used as the Geometry of a new InfoTextElement.

Next, create a new InfoTextElement, set its Geometry to the Point you just created, and QI for the IDocumentDefaultSymbols interface of the current MxDocument to set the IInfoElement::Symbol property.

Dim pElement As esriCarto.IElement, pInfoEl As IInfoElement
Set pElement = New GraphicElementVB.InfoTextElement
pElement.Geometry = pPoint
Set pInfoEl = pElement

Dim pDefaultSymbols As esriArcMapUI.IDocumentDefaultSymbols
Set pDefaultSymbols = pMxDoc
Set pInfoEl.Symbol = pDefaultSymbols.TextSymbol

Default symbols for any new graphic element should generally be taken from the IDocumentDefaultSymbols interface.

Add the InfoTextElement to the GraphicsContainer of the ActiveView, select the new element, and use a PartialRefresh to redraw that area of the view.

Dim pGCont As esriCarto.IGraphicsContainer
Dim pGContSelect As esriCarto.IGraphicsContainerSelect
Set pGCont = pMxDoc.ActiveView.GraphicsContainer
pGCont.AddElement pElement, 0
Set pGContSelect = pGCont
pGContSelect.UnselectAllElements
pGContSelect.SelectElement pElement
pMxDoc.ActiveView.PartialRefresh esriViewGraphics, pElement, Nothing

Last, to be consistent with other tools that create new elements, set the CurrentTool in ArcMap to be the Select Elements tool.

Dim pItem As esriFramework.ICommandItem, u As New esriSystem.UID
u = "{C22579D1-BC17-11D0-8667-0000F8751720}"
Set pItem = m_pApp.Document.CommandBars.Find(u)
Set m_pApp.CurrentTool = pItem

Provide standard implementations of all other members of ICommand and ITool. Register the command to the ESRI Mx Commands component category.

Using the NewInfoTextTool

In ArcMap, add the command to a toolbar by opening the Customize dialog box and dragging the command onto any toolbar. Select the NewInfoTextTool, then click a location on a view to add a new InfoTextElement at that location.

Right-click the element and choose Properties to view the element properties dialog box.

Creating a property page for the InfoTextElement

To edit the properties of any graphic element in ArcMap, click the pointer tool and right-click the graphic element in either data or layout view. Alternatively, select a number of graphic elements before right-clicking to see the properties common to all the selected elements.

Existing element property pages

The Properties dialog box will check for property pages in up to three component categories. Pages registered to ESRI Element Property Pages are always checked. If the element or elements being edited implement IMapFrame, the dialog box will also check pages registered to ESRI Map Property Pages; if the element or elements implement IFrameElement, the dialog box will also check pages registered to ESRI Frame Element Property Pages. The dialog box will return, containing all the pages for which Applies returns True.

By implementing IElement, the Size And Position property page will apply to your element—this page will assume that any element it receives also supports ITransform2D.

All elements will have the Size and Position property page—this relies on the IElement and ITransform2D interfaces.

As the user may have selected a number of elements, all element property pages should be able to cope when passed an IEnumElement reference instead of an IElement reference. In this case, the properties that have been changed in the page are applied to all the elements in the enumeration.

Creating the InfoPropertyPage

At this point, your users are only able to alter the properties of the IInfoElement interface programmatically. You will now create a simple property page to allow users to change which items of text are shown on the element (ShowUser, and so on) and the Symbol used to draw the text.

Add a class called InfoPropertyPage and a Form called frmInfoTextPropertyPage to your project. Register the class to the ESRI Element Property Pages component category.

Add check boxes to allow users to set the ShowUser, ShowComputer, ShowDocPath, ShowAuthor, and ShowTemplates properties individually. Also add a button to change the Symbol, and a text box to display the current font information.

You can use the EnableAppOptions property of the InfoTextElement to selectively disable the Document path, Author name, and Templates options if the element does not currently reside in the ArcMap application.

The property page form should contain controls allowing users to set all the properties of IInfoElement.

For full details of the code behind the Form, see the accompanying example code.

Implementing property page interfaces for the InfoPropertyPage

InfoPropertyPage is a standard implementation of a property page. See 'Property Pages' in Chapter 2 for more information on implementing a property page.

In the Applies method, iterate through the Objects SafeArray parameter and return True if you find an object that implements IInfoElement.

Dim pObj As Variant, i As Long
Objects.Reset
For i = 0 To Objects.Count - 1
     Set pObj = Objects.Next
     If Not pObj Is Nothing Then
          If TypeOf pObj Is GraphicElementVB.IInfoElement Then
               IComPropertyPage_Applies = True

If the parameter contains an IEnumElement reference, iterate each of the elements in the enumerations, and return True only if all of the elements in the enumeration implement IInfoElement.

ElseIf (TypeOf pObj Is esriCarto.IEnumElement) Then
  Dim pElements As esriCarto.IEnumElement, pCurrEl As esriCarto.IElement
  Dim bApplies As Boolean
  Set pElements = pObj
  pElements.Reset
  bApplies = True
  Do
    Set pCurrEl = pElements.Next
    If Not (pCurrEl Is Nothing) Then
      bApplies = (bApplies And _
       (TypeOf pCurrEl Is GraphicElementVB.IInfoElement))
    End If
  Loop While Not pCurrEl Is Nothing
  IComPropertyPage_Applies = bApplies
  Exit Function
End If

In the Applies and SetObjects property page methods, an element property page may receive either a reference to a single element or a reference to an enumeration of elements.
An element property page should only apply (Applies = True) if it can be used to edit all the elements passed to it.

To manage references to a number of elements and their properties, add a class called InfoElementsCollection to your project. This will act as a custom collection class; for details of the class, see the code in the accompanying project.

In the property page Form class, declare a member variable m_pElementColl, and provide access to this via a property.

Private m_pElementColl As InfoElementsCollection
...
Public Property Get InfoElements() As InfoElementsCollection
  Set InfoElements = m_pElementColl
End Property

Create the InfoElementsCollection class to help the property page manage multiple references to elements; an element property page may be displayed for more than one element.

In the SetObjects method, create a new InfoElementsCollection.

Private Sub IComPropertyPage_SetObjects(ByVal Objects As esriSystem.ISet)
  ...
  Set m_frmPage.InfoElements = New InfoElementsCollection

Again, iterate the Objects to check for objects that implement IElement or IEnumElement. If you receive an IEnumElements reference, add each element from the enumeration to the ElementCollection of the Form; otherwise, just add the single IElement to the collection.

If (TypeOf pObj Is IInfoElement) Then
  m_frmPage.InfoElements.Add pObj, Str(m_frmPage.InfoElements.Count)
ElseIf (TypeOf pObj Is esriCarto.IEnumElement) Then
  ..

In the Form, apply property changes to each of the members in this collection. If the property page is cancelled, the changes will be discarded by the property sheet.

SetObjects will also receive references to the Transformation, GraphicsContainer, and PageLayout (if applicable) of the element or elements. Your property page can use these objects, if required, to help edit the properties of an element.

You should add code to your Form to display the properties applicable to all the elements received—for example, if two elements were received, unequal properties can be indicated by graying-out the check box (not disabling it).

Dim pInfoEl As GraphicElementVB.IInfoElement, valChecked(5) As Integer
For Each pInfoEl In m_pElementColl
  valChecked(0) = valChecked(0) + Int(pInfoEl.ShowUser)
  valChecked(1) = valChecked(1) + Int(pInfoEl.ShowComputer)
  ...

In the code, changes are made directly to the elements. This means that there is no need to work out which controls have been changed and, hence, which properties need to be updated. Also, the Apply property page method does not need to do anything.

Private Sub SetShowUser(ByVal bShow As Boolean)
  Dim pInfoEl As GraphicElementVB.IInfoElement
  For Each pInfoEl In m_pElementColl
    pInfoEl.ShowUser = bShow
  Next pInfoEl
End Sub

Element property pages are not displayed as embedded pages; therefore, there is no need to implement IComEmbeddedPropertyPage. If you are working in VC++, you can return E_NOTIMPL from CreateCompatibleObject, although it is good practice to provide a complete implementation.

Compile and register the project again, and you will be able to set the properties of the InfoTextElement using this new user interface.

Back to top

Go to example code

See Also Creating other types of custom Element, Creating Custom Elements, and Creating Cartography.