ArcGIS Engine Developer Guide

C++ APPLICATION PROGRAMMING INTERFACE
Initiating the listening process
Once you have written your event class, you will need to set up your application
to listen for the events. This is a two-step process:
1. IEventListenerHelper->Startup: sets up a link between the sink (your object,
such as a MapControl) and the listener helper object.
This step will need to be done before realizing the top-level widget and entering
the main application loop.
2. IEventListenerHelper->AdviseEvents: sets up a link between the listener helper
object and the source of the events—for example, IActiveViewEvents. Since
the main events on the controls are implemented using IDispatch, you will pass
in NULL for the interface to listen to, as shown in the example below.
Where this step is taken will depend on the type of object on which you want to
listen. If you are listening on an object that does not change—for example, a
MapControl—you can do this right after you call Startup on the events. If, however,
you want to listen to an object that will change during a single run of the
application, such as the ActiveView, you will want to make this call each time
that object changes. For example, to listen to events on a MapControl’s
ActiveView, you would want to make this call in the MapControl’s OnMapReplaced
event. This does mean that you would also need to implement the MapControl’s
main events.
Ending the listening process
For your application to exit cleanly, you will need to stop your application from
listening for events before you shut it down. This is again a two-step process:
1. IEventListenerHelper->Shutdown: removes the link between the sink (your
object, such as a MapControl) and the listener helper object.
2. IEventListenerHelper->UnadviseEvents: removes the link between the listener
helper object and the source of the events—for example, IActiveViewEvents.
Since these steps will only need to be taken when the application is closed, both
calls will be made from the callback that listens for the application to be closed,
before IAoInitialize’s shutdown is called and before the application is uninitialized.
Main control events—Implemented with IDispatch
To handle the main events of the controls, write a class that inherits from a
helper interface that implements the events you are going to listen for. For example,
to listen for IPageLayoutControlEvents, write a class that inherits from
IPageLayoutControlEventsHelper. For further implementation details, see the
walkthrough ‘Writing a MapControl Event class’ in the developer help system
under Development Environments > C++ > Walkthroughs. You will then listen
for the events by using the helper interface IEventListenerHelper.
Include files
To use these events, you will need to include Ao/AoControls.h in your event
class’s header file.
Chapter 4 • Developer environments • 247