How to wire custom events using IActiveViewEvents

Summary
Wiring custom events requires multiple steps that can be confusing. There are several terms that are new to .NET, and the flow of using custom events can be difficult to follow when embedded in an application. This topic pulls from various other sources to further explain and tie together wiring events in Visual Basic .NET (VB .NET) using the IActiveViewEvents interface to demonstrate how it works.

About working with events

If necessary, see the following topics first to get a general understanding of how to work with events:

Wiring custom events using IActiveViewEvents

Do the following steps to wire and use events:
  1. Declare a delegate object variable that handles the specific event—A member variable ( m_ActiveViewEventsAfterDraw ) is declared that is global in scope for the Class Form1. This member variable is the delegate object that will be used later to hold a type-safe function pointer for the AddHandler and RemoveHandler statements. See the following code example:
[VB.NET] 
Private m_ActiveViewEventsAfterDraw As ESRI.ArcGIS.Carto.IActiveViewEvents_AfterDrawEventHandler
In VB .NET, the various IActiveViewEvents handlers are not displayed in IntelliSense in Visual Studio. They are considered hidden types and do not display as a drop-down option when typing the dot (.) while coding. However, you can view the names of the hidden types in the Visual Studio Object Browser and in the ArcObjects Help system. See the following screen shot of the Object Browser:
  1. Create an instance of the delegate using the AddressOf operator—The delegate object member variable (m_ActiveViewEventsAfterDraw) is set to an instance of the IActiveViewEvents_AfterDrawEventHandler interface. This is a type-safe pointer to the procedure (that is, a sub or function) to accomplish the work of your event. The sub, OnActiveViewEventsAfterDraw, is the procedure that does the work whenever this event is fired. See the following code example:
[VB.NET] 
m_ActiveViewEventsAfterDraw = New ESRI.ArcGIS.Carto.IActiveViewEvents_AfterDrawEventHandler(AddressOf OnActiveViewEventsAfterDraw)
  1. Dynamically associate an event handler to the delegate object—Using the AddHandler statement, specify which ArcObjects event uses your delegate. The delegate object member variable (m_ActiveViewEventsAfterDraw) is used for the .AfterDraw event of the IActiveViewEvents_Event interface.

    In ArcObjects .NET, the event interfaces all have an _Event suffix. These event interfaces (also known as outbound interfaces) are automatically suffixed with _Event by the type library importer. When programming with ArcObjects .NET, use the event interfaces with the appended _Event suffix as shown in the Visual Studio Object Browser. Again, in VB .NET, the various _Event handlers are not displayed in IntelliSense in Visual Studio. They are considered hidden types and do not display as a drop-down option when typing the dot (.) while coding. See the following screen shots:


  1. Dynamically remove an event handler—Using the RemoveHandler statement, specify which ArcObjects event you want to remove from a particular delegate. The delegate object member variable (m_ActiveViewEventsAfterDraw) is removed as the delegate event of the .AfterDraw event of the IActiveViewEvents_Event interface. See the following code example:
[VB.NET] 
RemoveHandler CType(map, ESRI.ArcGIS.Carto.IActiveViewEvents_Event).AfterDraw, m_ActiveViewEventsAfterDraw
Dynamically adding and removing event handlers in ArcObjects .NET allows for powerful and flexible applications. Depending on your application, you can code one type of behavior (for example, inserting balloon text boxes with a mouse click) in one part of your application and a different behavior in another part of your application (for example, performing hyperlinks to other documents with a mouse click) by dynamically wiring events to custom procedures. Delegates are the mechanism for which a type-safe pointer can be utilized to use the AddHandler and RemoveHandler statements.

The following code example shows what a final product looks like using event handlers and follows the four steps previously discussed:
[VB.NET] 
Public Class Form1
    'Step 1: Declare a delegate object variable that will handle the specific event.
    Private m_ActiveViewEventsAfterDraw As ESRI.ArcGIS.Carto.IActiveViewEvents_AfterDrawEventHandler

    Private Sub AddHandlerEx()
        Dim application2 As ESRI.ArcGIS.Framework.IApplication = CType(EventHandlerExample.My.ThisApplication, ESRI.ArcGIS.Framework.IApplication)
        Dim mxDocument As ESRI.ArcGIS.ArcMapUI.IMxDocument = application2.Document
        Dim activeView As ESRI.ArcGIS.Carto.IActiveView = mxDocument.ActiveView
        Dim map As ESRI.ArcGIS.Carto.IMap = activeView.FocusMap
        'Step 2: Create an instance of the delegate using the AddressOf operator and add it to
        'the AfterDraw event.
        m_ActiveViewEventsAfterDraw = New ESRI.ArcGIS.Carto.IActiveViewEvents_AfterDrawEventHandler(AddressOf OnActiveViewEventsAfterDraw)
        'Step 3: Dynamically associate an event handler to the delegate object.
        AddHandler CType(map, ESRI.ArcGIS.Carto.IActiveViewEvents_Event).AfterDraw, m_ActiveViewEventsAfterDraw
    End Sub


    Private Sub RemoveHandlerEx()
        Dim application2 As ESRI.ArcGIS.Framework.IApplication = CType(EventHandlerExample.My.ThisApplication.m_application, ESRI.ArcGIS.Framework.IApplication)
        Dim mxDocument As ESRI.ArcGIS.ArcMapUI.IMxDocument = application2.Document
        Dim activeView As ESRI.ArcGIS.Carto.IActiveView = mxDocument.ActiveView
        Dim map As ESRI.ArcGIS.Carto.IMap = activeView.FocusMap
        'Step 4: Dynamically remove an event handler.
        RemoveHandler CType(map, ESRI.ArcGIS.Carto.IActiveViewEvents_Event).AfterDraw, m_ActiveViewEventsAfterDraw
    End Sub


    Private Sub OnActiveViewEventsAfterDraw(ByVal Display As ESRI.ArcGIS.Display.IDisplay, ByVal phase As ESRI.ArcGIS.Carto.esriViewDrawPhase)
        'Add your code here.
        System.Windows.Forms.MessageBox.Show("AfterDraw")
    End Sub

End Class





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