Event Handling With ATL

Event Handling and ATL

ATL helps you with all three elements required for handling events: implementing the event interface, advising the event source, and unadvising the event source. The precise steps you'll need to take will depend largely on the type of the event interface as well as on the performance requirements of your particular application.

The most common ways of implementing an interface using ATL are:

• Deriving from a custom interface directly.
  
  
• Deriving from IDispatchImpl for dual interfaces described in a type library.
  
  
• Deriving from IDispEventImpl for dispinterfaces described in a type library.
  
  
• Deriving from IDispEventSimpleImpl for dispinterfaces not described in a type library or when you want to improve efficiency by not loading the type information at run time.

If you are implementing a custom or dual interface, you should advise the event source by calling AtlAdvise, CComPtr::Advise, or CComQIPtr::Advise. You will need to keep track of the cookie returned by the call yourself. Call AtlUnadvise to break the connection.

If you are implementing a dispinterface using IDispEventImpl or IDispEventSimpleImpl, you should advise the event source by calling IDispEventSimpleImpl::DispEventAdvise. Call IDispEventSimpleImpl::DispEventUnadvise to break the connection.

If you are using IDispEventImpl as a base class of a composite control, the event sources listed in the sink map will be advised and unadvised automatically using CComCompositeControl::AdviseSinkMap.

The IDispEventImpl and IDispEventSimpleImpl classes manage the cookie for you.