Listening to the OnValidate event for a geodatabase topology


Summary
The ITopologyClassEvents interface exposes an event that event handlers can listen to, allowing custom applications and extensions to respond to topology validation. This topic explains how to use handlers for this event in C# and VB .NET.

About topology class events

The ITopologyClassEvents_Event interface allows listeners to subscribe to events from a topology. This interface exposes a single event, OnValidate, which is raised when a topology validates a dirty area. This interface can be accessed by casting an ITopology reference.
Use of ITopologyClassEvents for building class extensions, or other event listeners, when listening to the OnValidate event from the ITopologyExtensionEvents_Event interface in the EditorExt assembly is not an option. An example of when this can occur is in cases where clients other than ArcMap are validating the topology.
The OnValidate event has an IGeometry parameter that is a polygon, multi-part polygon, or collection of polygons, which represents the dirty areas validated. Note that this geometry is not necessarily the same as the envelope passed to the ITopology.ValidateTopology method, but represents the dirty area or areas within the envelope that were validated (which might be the entire envelope).
This topic explains how to implement an event listener dedicated to listening to the OnValidate event.
In some cases, the OnValidate event will not be raised when ITopology.ValidateTopology is called; specifically, if the validated area does not contain or intersect a dirty area.

Creating an event handler

An event handler is a method within the event listener that defines the application's behavior in response to an event. Event handlers must match the return type and parameter types of the published events, but can be given any name. The following code example shows an event handler for the OnValidate event that writes the extent of the validated area to the console:
[C#] 
public void OnValidate(IGeometry validatedArea)
{
    // Get the validated area's envelope and display its coordinates.
    IEnvelope validatedEnvelope = validatedArea.Envelope;
    Console.WriteLine("X and Y minimums: {0}, {1}", validatedEnvelope.XMin,
        validatedEnvelope.YMin);
    Console.WriteLine("X and Y maximums: {0}, {1}", validatedEnvelope.XMax,
        validatedEnvelope.YMax);
}
[VB.NET] 
Private Sub OnValidate(ByVal validatedArea As IGeometry)
    ' Get the validated area's envelope and display its coordinates.
    Dim validatedEnvelope As IEnvelope = validatedArea.Envelope
    Console.WriteLine("X and Y minimums: {0}, {1}", validatedEnvelope.XMin, validatedEnvelope.YMin)
    Console.WriteLine("X and Y maximums: {0}, {1}", validatedEnvelope.XMax, validatedEnvelope.YMax)
End Sub

Adding handlers to events

Adding a handler to an event varies slightly between C# and VB .NET:
  • In C# an instance of the event's delegate type must be created to encapsulate the event handler. The delegate is instantiated much like a class, by using the "new" keyword. In VB .NET, the AddressOf operator is used to create a procedure delegate for the method.
  • The delegate instance can then be added to the appropriate event on the event interface. In C#, the += operator is used for this, while in VB .NET the AddHandler statement is used.
The following code example is an event listener's constructor, which instantiates a delegate and adds it to the OnValidate event of a topology's event interface. To tightly couple an event listener with an object class, the event listener's constructor can accept an ITopology parameter, then cast it to the event interface.
[C#] 
public TopologyEventListener(ITopology topology)
{
    // Cast the topology to the event interface.
    ITopologyClassEvents_Event topologyClassEvent = (ITopologyClassEvents_Event)
        topology;

    // Instantiate the delegate type and add it to the event.
    topologyClassEvent.OnValidate += new ITopologyClassEvents_OnValidateEventHandler
        (OnValidate);
}
[VB.NET] 
Public Sub New(ByVal topology As ITopology)
    ' Cast the topology to the event interface.
    Dim topologyClassEvent As ITopologyClassEvents_Event = CType(topology, ITopologyClassEvents_Event)
    
    ' Instantiate the delegate type and add it to the event.
    AddHandler topologyClassEvent.OnValidate, AddressOf OnValidate
End Sub

Instantiating a listener

Once the listener is completed, it can be used within custom applications. Instantiating a listener is simple, as shown in the following code example:
[C#] 
// Open the topology from the feature dataset.
ITopologyContainer topologyContainer = (ITopologyContainer)featureDataset;
ITopology topology = topologyContainer.get_TopologyByName("Landbase_Topology");

// Create the topology event listener.
TopologyEventListener eventListener = new TopologyEventListener(topology);
[VB.NET] 
' Open the topology from the feature dataset.
Dim topologyContainer As ITopologyContainer = CType(featureDataset, ITopologyContainer)
Dim topology As ITopology = topologyContainer.TopologyByName("Landbase_Topology")

' Create the topology event listener.
Dim eventListener As TopologyEventListener = New TopologyEventListener(topology)

Complete listener implementation

The following code example shows the full implementation of the event listener as previously described:
[C#] 
public class TopologyEventListener
{
    public TopologyEventListener(ITopology topology)
    {
        // Cast the topology to the event interface.
        ITopologyClassEvents_Event topologyClassEvent = (ITopologyClassEvents_Event)
            topology;

        // Instantiate the delegate type and add it to the event.
        topologyClassEvent.OnValidate += new
            ITopologyClassEvents_OnValidateEventHandler(OnValidate);
    }

    public void OnValidate(IGeometry validatedArea)
    {
        // Get the validated area's envelope and display its coordinates.
        IEnvelope validatedEnvelope = validatedArea.Envelope;
        Console.WriteLine("X and Y minimums: {0}, {1}", validatedEnvelope.XMin,
            validatedEnvelope.YMin);
        Console.WriteLine("X and Y maximums: {0}, {1}", validatedEnvelope.XMax,
            validatedEnvelope.YMax);
    }
}
[VB.NET] 
Public Class TopologyEventListener

    Public Sub New(ByVal topology As ITopology)
        ' Cast the topology to the event interface.
        Dim topologyClassEvent As ITopologyClassEvents_Event = CType(topology, ITopologyClassEvents_Event)
        
        ' Instantiate the delegate type and add it to the event.
        AddHandler topologyClassEvent.OnValidate, AddressOf OnValidate
    End Sub
    
    Public Sub OnValidate(ByVal validatedArea As IGeometry)
        ' Get the validated area's envelope and display its coordinates.
        Dim validatedEnvelope As IEnvelope = validatedArea.Envelope
        Console.WriteLine("X and Y minimums: {0}, {1}", validatedEnvelope.XMin, validatedEnvelope.YMin)
        Console.WriteLine("X and Y maximums: {0}, {1}", validatedEnvelope.XMax, validatedEnvelope.YMax)
    End Sub

End Class





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 for Desktop Basic ArcGIS for Desktop Basic
ArcGIS for Desktop Standard ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced ArcGIS for Desktop Advanced
Engine Developer Kit Engine: Geodatabase Update