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:

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

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

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:

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)

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

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

How to listen to document events

Getting a reference to the document object

Wiring the document event in the event interface

Registering the handler method to the event

Complete code

Code fragments

See Also: