How to listen to document events


Summary
ArcGIS for Desktop applications are document based. Document events are fired when a document is created, opened, or closed. This topic shows how to hook up these event handlers in your custom .NET components.


Getting a reference to the document object

To get a reference to the document object, follow these steps:
  1. To listen to document events of an ArcGIS for Desktop application, get a reference to the document object from the application. (Code)

    The following table shows example entry points to get a reference to the application object:
Implementation
Method and parameter
Command
ICommand.OnCreate() hook parameter
Extension
IExtension.Startup() initializationData parameter
 
  1. Once you get a reference to the document, cast it to its event interface. See the following table:
Application
Default event interface
ArcMap
ESRI.ArcGIS.ArcMapUI.MxDocument
ArcScene
ESRI.ArcGIS.ArcScene.SxDocument
ArcGlobe
ESRI.ArcGIS.ArcGlobe.GMxDocument
 
  1. Although the default event interface for each application is different, declare the type of the variable as the common IDocumentEvents_Event interface. In ArcMap for example, add a reference to the ESRI.ArcGIS.ArcMapUI assembly to your project and declare a modular variable, m_docEvents, to hold on to the document object. (Code)

    You can also reference the document by the event interfaces in the following table:
Application
Namespace
Event interface
ArcMap
ESRI.ArcGIS.ArcMapUI
IDocumentEvents_Event
ArcScene
ESRI.ArcGIS.ArcScene
ISxDocumentEvents_Event
ArcGlobe
ESRI.ArcGIS.ArcGlobe
IGMxDocumentEvents_Event

Wiring the document event in the event interface

When wiring events, use the += operator in C# and the AddHandler keyword in Visual Basic (VB) .NET. The NewDocument event is wired to listen to document creation. (Code)

Registering the handler method to the event

To register the handler method to the event, follow these steps:
  1. Define a method to handle the event. This handler method is called when the event is fired. The handler method signature must match the event you are listening to. For the NewDocument event, the handler method signature is simple. (Code)
    • C#—The Visual Studio autocomplete feature for C# is very helpful. Once you type the += operator, an autocomplete ToolTip is shown and code is automatically stubbed out when the Tab key is pressed twice. (Code)
    • VB .NET—You have to write the handler method and use the AddressOf keyword to reference the method to complete the AddHandler statement. (Code)
  1. Add code in the event handler method to complete this task.
After you enter the += operator, Visual Studio automatically stubs out of the remainder of the declaration and the event handler function if you press the Tab key twice.

Complete code

See the following example of the complete code:
[C#]
using ESRI.ArcGIS.Framework;
using ESRI.ArcGIS.ArcMapUI;

namespace ArcGISProject
{
    public class howToClass
    {
        //Event member variable.
        private IDocumentEvents_Event m_docEvents = null;

        //Wiring.
        private void SetUpDocumentEvent(IDocument myDocument)
        {
            m_docEvents = myDocument as IDocumentEvents_Event;
            m_docEvents.NewDocument += new IDocumentEvents_NewDocumentEventHandler
                (howToClass_NewDocument);
        }

        //Event handler method.
        void howToClass_NewDocument()
        {
            System.Windows.MessageBox.Show("New document at: " +
                DateTime.Now.ToLongTimeString());
        }

    }
}
[VB.NET]
Imports ESRI.ArcGIS.Framework
Imports ESRI.ArcGIS.ArcMapUI

Public Class howToClass
    
    'Event member variable.
    Private m_docEvents As IDocumentEvents_Event
    
    'Wiring.

    Sub SetUpDocumentEvent(myDocument As IDocument)
        m_docEvents = CType(myDocument, IDocumentEvents_Event)
        AddHandler m_docEvents.NewDocument, AddressOf OnNewDocument
    End Sub
    
    'Event handler method.

    Sub OnNewDocument()
        MsgBox("New document at: " + DateTime.Now.ToLongTimeString())
    End Sub
    
End Class

Code fragments

The code fragments for the referenced steps are as follows:
  • Code 1 : Getting the document object from the application—The following code requires referencing the ESRI.ArcGIS.Framework assembly in the project:
[C#]
IApplication app = hook as IApplication;
IDocument appDocument = app.Document;
[VB.NET]
Dim app As IApplication = CType(hook, IApplication)
Dim appDocument As IDocument = app.Document
  • Code 2 : Declaring an IDocumentEvents_Event variable—The following code requires referencing ESRI.ArcGIS.Framework and ESRI.ArcGIS.ArcMapUI in the project:
[C#]
public class howToClass
{
    private IDocumentEvents_Event m_docEvents = null;

    private void SetUpDocumentEvent(IDocument myDocument)
    {
        m_docEvents = myDocument as IDocumentEvents_Event;
        ...
    }
}
[VB.NET]
Public Class howToClass
    Private m_docEvents As IDocumentEvents_Event
    
    Sub SetUpDocumentEvent(myDocument As IDocument)
        m_docEvents = CType(myDocument, IDocumentEvents_Event)
        ...
    End Sub

End Class
  • Code 3 : Wiring NewDocument event—The following code requires referencing ESRI.ArcGIS.Framework and ESRI.ArcGIS.ArcMapUI in the project:
[C#]
private IDocumentEvents_Event m_docEvents = null;

private void SetUpDocumentEvent(IDocument myDocument)
{
    m_docEvents = myDocument as IDocumentEvents_Event;
    m_docEvents.NewDocument += ...
}
[VB.NET]
Private m_docEvents As IDocumentEvents_Event

Sub SetUpDocumentEvent(myDocument As IDocument)
    m_docEvents = CType(myDocument, IDocumentEvents_Event)
    AddHandler m_docEvents.NewDocument, ...
End Sub
  • Code 4 : NewDocument event signature—See the following code:
[C#]
void OnNewDocument()
[VB.NET]
Sub OnNewDocument()
  • Code 5 : Wiring the NewDocument event to the handling method (C#)—The following code requires referencing ESRI.ArcGIS.Framework and ESRI.ArcGIS.ArcMapUI in the project:
[C#]
m_docEvents.NewDocument += new IDocumentEvents_NewDocumentEventHandler
    (howToClass_NewDocument);
... 

void howToClass_NewDocument(){}
  • Code 6 : Wiring the NewDocument event to the handling method (VB .NET)—The following code requires referencing ESRI.ArcGIS.Framework and ESRI.ArcGIS.ArcMapUI in the project:
[VB.NET]
AddHandler m_docEvents.NewDocument, AddressOf OnNewDocument
...

Sub OnNewDocument()
    
End Sub


See Also:

How to wire ArcObjects .NET events




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