Microsoft KB Archive/309294

= HOW TO: Handle Word Events by Using Visual C++ .NET and MFC =

Article ID: 309294

Article Last Modified on 6/29/2007

-

APPLIES TO


 * Microsoft Visual C++ .NET 2003 Standard Edition
 * Microsoft Visual C++ .NET 2002 Standard Edition
 * Microsoft Office Word 2003
 * Microsoft Word 2002 Standard Edition
 * Microsoft Word 2000 Standard Edition

-



This article was previously published under Q309294







For a Microsoft Visual C# .NET version of this article, see 302817.



For a Microsoft Visual Basic .NET version of this article, see 302816.

IN THIS TASK
SUMMARY
 * Create a C++ Automation Client to Handle Microsoft Word Events
 * Test the Application
 * Word Application Events

REFERENCES



Note Microsoft Visual C++ .NET (2002) supports both the managed code model that is provided by the Microsoft .NET Framework and the unmanaged native Microsoft Windows code model. The information in this article applies only to unmanaged Visual C++ code.



SUMMARY
This step-by-step article describes how to handle events in Word from an Automation client that is created with Visual C++ .NET by using Microsoft Foundation Classes (MFC). The article illustrates traditional COM event sinking.

back to the top

Create a C++ Automation Client to Handle Microsoft Word Events
 Follow the steps in the &quot;Create an Automation Client&quot; section of the following Microsoft Knowledge Base article to create a basic Automation client:

307473 HOWTO: Use a Type Library for Office Automation from Visual C++ .NET

In step 1, type WordEvents1 for the name of the project.

In step 3, change the ID of the first button to ID_STARTSINK and the caption to Start Event Sink. Add a second button, and then change the ID of the second button to ID_STOPSINK and the caption to Stop Event Sink.

In step 4, use the Word type library, and select the following Word interfaces:  _Application _Document Documents Selection</li> Window</li></ul> </li> On the Project menu, click Add Class. Select the Generic C++ class in the list of templates, and then click Open.</li> In the Generic C++ Class Wizard dialog box, type CAppEventListener for the class name, type IDispatch for the base class, and then click Finish.</li>  Replace all of the code in Appeventslistener.h with the following:
 * 1) pragma once
 * 2) include &quot;oaidl.h&quot;
 * 3) include &quot;CApplication.h&quot;
 * 4) include &quot;CDocument0.h&quot;
 * 5) include &quot;CDocuments.h&quot;
 * 6) include &quot;CSelection.h&quot;
 * 7) include &quot;CWindow0.h&quot;

const IID IID_IApplicationEvents2 = {0x000209fe,0x0000,0x0000,{0xc0,0x00,0x00,0x00,0x00,0x00,0x00,0x46}}; // Parsed UUID for WordApplicationEvents2 dispinterface. class CAppEventListener : public IDispatch { private: int m_refCount;

public: //Constructor. CAppEventListener; //Destructor ~CAppEventListener;

/***** IUnknown Methods *****/ STDMETHODIMP QueryInterface(REFIID riid, void ** ppvObj); STDMETHODIMP_(ULONG) AddRef; STDMETHODIMP_(ULONG) Release;

/***** IDispatch Methods *****/ STDMETHODIMP GetTypeInfoCount(UINT *iTInfo); STDMETHODIMP GetTypeInfo(UINT iTInfo, LCID lcid,      ITypeInfo **ppTInfo); STDMETHODIMP GetIDsOfNames(REFIID riid,       OLECHAR **rgszNames,       UINT cNames,  LCID lcid,      DISPID *rgDispId); STDMETHODIMP Invoke(DISPID dispIdMember, REFIID riid, LCID lcid,     WORD wFlags, DISPPARAMS* pDispParams,      VARIANT* pVarResult, EXCEPINFO* pExcepInfo,      UINT* puArgErr);

// The following three examples are patterns for the // declaration, definition, and implementation of   //  event handler methods. STDMETHODIMP WindowSelectionChange(CSelection* Sel); STDMETHODIMP WindowBeforeRightClick(CSelection* Sel,     VARIANT_BOOL* Cancel); STDMETHODIMP WindowDeactivate(IUnknown* Doc,      CWindow0* Wn); // End of examples. }; NOTE: The value for the IID_IApplicationEvents2 variable is derived from the Word object library. For more information, see the &quot;Word Application Events&quot; section. </li>  Replace all of the code in Appeventlistener.cpp with the following code:
 * 1) include &quot;stdafx.h&quot;
 * 2) include &quot;AppEventListener.h&quot;

//Constructor. CAppEventListener::CAppEventListener {  m_refCount = 0; }

//Destructor. CAppEventListener::~CAppEventListener {}

/******************************************************************************
 * IUnknown Interfaces -- All COM objects must implement, either
 * directly or indirectly, the IUnknown interface.

/****************************************************************************** STDMETHODIMP CAppEventListener::QueryInterface(REFIID riid, void ** ppvObj) {  if (riid == IID_IUnknown){ *ppvObj = static_cast<IUnknown*>(this); }
 * QueryInterface -- Determines if this component supports the
 * requested interface, places a pointer to that interface in ppvObj if it is
 * available, and returns S_OK. If not, sets ppvObj to NULL and returns
 * E_NOINTERFACE.

else if (riid == IID_IDispatch){ *ppvObj = static_cast<IDispatch*>(this); }

else if (riid == IID_IApplicationEvents2){ *ppvObj = static_cast<IDispatch*>(this); }

else{ *ppvObj = NULL; return E_NOINTERFACE; }

static_cast<IUnknown*>(*ppvObj)->AddRef; return S_OK; }

/****************************************************************************** STDMETHODIMP_(ULONG) CAppEventListener::AddRef {  return ++m_refCount; }
 * AddRef -- In order to allow an object to delete itself when
 * it is no longer needed, it is necessary to maintain a count of all
 * references to this object. When a new reference is created, this function
 * increments the count.

/****************************************************************************** STDMETHODIMP_(ULONG) CAppEventListener::Release {  m_refCount--;
 * Release -- When a reference to this object is removed, this
 * function decrements the reference count. If the reference count is 0,
 * this function deletes this object and returns 0.

if (m_refCount == 0) {     delete this; return 0; }  return m_refCount; }

/******************************************************************************
 * IDispatch Interface -- This interface allows this class to be used as an
 * Automation server, allowing its functions to be called by other COM
 * objects.

/****************************************************************************** STDMETHODIMP CAppEventListener::GetTypeInfoCount(UINT *iTInfo) {  *iTInfo = 0; return S_OK; }
 * GetTypeInfoCount -- This function determines if the class supports type
 * information interfaces or not. It places 1 in iTInfo if the class supports
 * type information and 0 if it does not.

/****************************************************************************** STDMETHODIMP CAppEventListener::GetTypeInfo(UINT iTInfo, LCID lcid,                                            ITypeInfo **ppTInfo) {  return E_NOTIMPL; }
 * GetTypeInfo -- Returns the type information for the class. For classes
 * that do not support type information, this function returns E_NOTIMPL;

/****************************************************************************** STDMETHODIMP CAppEventListener::GetIDsOfNames(REFIID riid,                                               OLECHAR **rgszNames,                                               UINT cNames,  LCID lcid,                                              DISPID *rgDispId) {  return E_NOTIMPL; }
 * GetIDsOfNames -- Takes an array of strings and returns an array of DISPIDs
 * that correspond to the methods or properties indicated. If the name is not
 * recognized, it returns DISP_E_UNKNOWNNAME.

/****************************************************************************** STDMETHODIMP CAppEventListener::Invoke(DISPID dispIdMember, REFIID riid, LCID lcid,                                      WORD wFlags, DISPPARAMS* pDispParams,                                       VARIANT* pVarResult,                                       EXCEPINFO* pExcepInfo,                                       UINT* puArgErr) {  //Validate arguments. if ((riid != IID_NULL)) return E_INVALIDARG;
 * Invoke -- Takes a dispid and uses it to call another of the methods of this
 * class. Returns S_OK if the call was successful.

HRESULT hr = S_OK; // Initialize.

switch(dispIdMember){ case 0x00000001: //Startup; Word is started before this is fired. OutputDebugString(&quot;Startup\n&quot;); break; case 0x00000002: //Quit; OutputDebugString( &quot;Quit\n&quot;); break; case 0x00000003: //DocumentChange; OutputDebugString( &quot;DocumentChange\n&quot;); break; case 0x00000004: //DocumentOpen([in] Document* Doc); OutputDebugString( &quot;DocumentOpen\n&quot;); break; case 0x00000005: // No dispID OutputDebugString( &quot;No dispID yields 00005. This is wierd!\n&quot;); break; case 0x00000006: // DocumentBeforeClose([in] Document* Doc, [in] VARIANT_BOOL* Cancel); OutputDebugString( &quot;DocumentBeforeClose\n&quot;); break; case 0x00000007: // DocumentBeforePrint([in] Document* Doc, [in] VARIANT_BOOL* Cancel); OutputDebugString( &quot;DocumentBeforePrint\n&quot;); break; case 0x00000008: // DocumentBeforeSave([in] Document* Doc, [in] VARIANT_BOOL* SaveAsUI, [in] VARIANT_BOOL* Cancel); OutputDebugString( &quot;DocumentBeforeSave\n&quot;); break; case 0x00000009: // NewDocument([in] Document* Doc); OutputDebugString( &quot;New Document\n&quot;); break; case 0x0000000a: // WindowActivate([in] Document* Doc, [in] Window* Wn); OutputDebugString( &quot;WindowActivate\n&quot;); break;

// Next 3 illustrate passing parameters to real event handler functions.

case 0x0000000b: // WindowDeactivate([in] Document* Doc, [in] Window* Wn); // The client(in this case, Word) sends arguments to INVOKE // in a parameter array, stacked in reverse order, but you // need to send them to the called function in not-reverse order. if(pDispParams->cArgs!=2) return E_INVALIDARG; else {           if(pDispParams->rgvarg[0].vt & VT_BYREF) {              if(pDispParams->rgvarg[0].vt & VT_BYREF) {                 WindowDeactivate(*(pDispParams->rgvarg[1].ppunkVal),                     ((CWindow0*)*(pDispParams->rgvarg[0].ppunkVal))); }              else {                 WindowDeactivate(*(pDispParams->rgvarg[1].ppunkVal),                     ((CWindow0*)(pDispParams->rgvarg[0].punkVal))); }           }            else {              if(pDispParams->rgvarg[0].vt & VT_BYREF) {                 WindowDeactivate((pDispParams->rgvarg[1].punkVal),                     ((CWindow0*)*(pDispParams->rgvarg[0].ppunkVal))); }              else {                 WindowDeactivate((pDispParams->rgvarg[1].punkVal),                     ((CWindow0*)(pDispParams->rgvarg[0].punkVal))); }

}        }         break; case 0x0000000c: // WindowSelectionChange([in] Selection* Sel); if (pDispParams->cArgs != 1) return E_INVALIDARG; else{ if (pDispParams->rgvarg[0].vt & VT_BYREF) WindowSelectionChange( ((CSelection*)*(pDispParams->rgvarg[0].ppunkVal)) ); else WindowSelectionChange((CSelection*) pDispParams->rgvarg[0].punkVal ); }        break; case 0x0000000d: // WindowBeforeRightClick([in] Selection*  Sel, [in] VARIANT_BOOL* Cancel); if(pDispParams->cArgs !=2) return E_INVALIDARG; else {           if(pDispParams->rgvarg[1].vt & VT_BYREF) // The pointer to bool is always by reference. {              WindowBeforeRightClick( // call the function                  ((CSelection*)*(pDispParams->rgvarg[1].ppunkVal)),                  pDispParams->rgvarg[0].pboolVal); }           else {              WindowBeforeRightClick(  // Call the function.                  ((CSelection*)(pDispParams->rgvarg[1].punkVal)),                  pDispParams->rgvarg[0].pboolVal); }        }         break; case 0x0000000e: // WindowBeforeDoubleClick([in] Selection*  Sel, [in] VARIANT_BOOL* Cancel); OutputDebugString( &quot;WindowBeforeDoubleClick\n&quot;); break; default: OutputDebugString( &quot;An event with a dispID above 000e\n&quot;); break; }  return hr; }

/************************************************************************************ STDMETHODIMP CAppEventListener::WindowSelectionChange(CSelection* Sel) {  OutputDebugString(&quot;WindowSelectionChange\n&quot;); return S_OK; } STDMETHODIMP CAppEventListener::WindowBeforeRightClick(CSelection* Sel, VARIANT_BOOL* Cancel) {  OutputDebugString(&quot;WindowBeforeRightClick\n&quot;); return S_OK; } STDMETHODIMP CAppEventListener::WindowDeactivate(IUnknown* Doc, CWindow0* Wn) {  OutputDebugString(&quot;WindowDeactivate\n&quot;); return S_OK; }                   </li>  Double-click the ID_STARTSINK control on your dialog box and add the following code to CWordEvents1Dlg::OnBnClickedStartsink: void CWordEvents1Dlg::OnBnClickedStartsink {  // Common OLE-variants. These are easy variants to use for calling arguments. COleVariant covTrue((short)TRUE), covFalse((short)FALSE), covOptional((long)DISP_E_PARAMNOTFOUND, VT_ERROR); COleException e;
 * Sample event handler functions, called from the above switch.
 * Fill each with the code needed to handle the event according to
 * the needs and design of your application.

CDocuments oDocs; // oDocs is the Documents Collection. CDocument0 oDoc; // oDoc is the Document object. CString str; HRESULT hr = S_OK;

try {     // Start Word and get an Application object. if(!m_wordApplication.CreateDispatch(&quot;Word.Application&quot;, &e)) {        str.Format(&quot;Problem instantiating Word. Error is %ld <0x%08lx>&quot;, e.m_sc, e.m_sc); AfxMessageBox(str,MB_SETFOREGROUND); return; }     else // Success. {        //Make the application visible. m_wordApplication.put_Visible(TRUE); }

oDocs = m_wordApplication.get_Documents; oDoc = oDocs.Add(covOptional,covOptional,covOptional,covTrue);

//Do not try to hook up more than once. if (m_pAppEventListener != NULL) return;

// Get IConnectionPointContainer interface for the server. IConnectionPointContainer *pConnPtContainer= NULL; hr = m_wordApplication.m_lpDispatch->QueryInterface(        IID_IConnectionPointContainer,         (void **)&pConnPtContainer ); if (SUCCEEDED(hr)){

// Find the connection point for events that you are interested in. hr = pConnPtContainer->FindConnectionPoint(           IID_IApplicationEvents2,            &m_pConnectionPoint            ); if (SUCCEEDED(hr)){

//Create a new CAppEventListener. m_pAppEventListener = new CAppEventListener; m_pAppEventListener->AddRef;

// Set up advisory connection. hr = m_pConnectionPoint->Advise(m_pAppEventListener,               &m_dwConnectionCookie);

// Release the IConnectionPointContainer interface. pConnPtContainer->Release; }     }   }   catch(COleException* e)   { str.Format(&quot;Error in Try..Catch was 0x%08lx&quot;, e->m_sc); AfxMessageBox(str, MB_SETFOREGROUND); return; } }                   </li>  Double-click the ID_STOPSINK control on your dialog box and add the following code to CWordEvents1Dlg::OnBnClickedStopsink: void CWordEvents1Dlg::OnBnClickedStopsink {  //If the connection point has been advised, unadvise it and clean up. if (m_pConnectionPoint != NULL){ m_pConnectionPoint->Unadvise( m_dwConnectionCookie ); m_dwConnectionCookie = 0; m_pConnectionPoint->Release; m_pConnectionPoint = NULL; }

if (m_pAppEventListener != NULL){ m_pAppEventListener->Release; m_pAppEventListener = NULL; }

m_wordApplication.ReleaseDispatch; }                   </li>  Append the following code to CWordEvents1Dlg::OnInitDialog in Wordevents1dlg.cpp: m_pAppEventListener = NULL; m_pConnectionPoint = NULL; m_dwConnectionCookie = 0; </li>  Add the following include to Wordevents1dlg.h:                    </li>  In the Wordevents1dlg.h file, add the following to the list of protected variables in the //Implementation section of CWordEvents1Dlg: CApplication m_wordApplication; CAppEventListener* m_pAppEventListener; IConnectionPoint* m_pConnectionPoint; DWORD m_dwConnectionCookie; </li></ol>
 * 1) include &quot;AppEventListener.h&quot;

back to the top

Test the Application
<ol> Press F5 to build and run the program.</li> Click Start Events Sink on the form to start Word, create a new Word document, and set up the event handlers.</li> Test the event handlers. To do this, follow these steps: <ol style="list-style-type: lower-alpha;"> Double-click anywhere in the document.</li> Right-click anywhere in the document.</li> <li>Save the document.</li> <li>Close the document.</li> <li> In Visual Studio, select Other Windows on the View menu, and then select Output to view the Output window. The Output window displays a trace of the events that were handled as well as the order in which the events were handled: <pre class="fixed_text">DocumentChange WindowActivate WindowBeforeDoubleClick WindowSelectionChange WindowSelectionChange WindowBeforeRightClick DocumentBeforeSave DocumentBeforeClose WindowDeactivate DocumentChange </li></ol> </li> <li>Click Stop Events Sink to stop handling Word events.</li> <li>Quit your program, and then quit Word.</li></ol>

back to the top

Word Application Events
To verify the universally unique identifier (UUID) for a set of Word events, follow these steps: <ol> <li>On the Tools menu in Visual Studio .NET, click OLE/COM Object Viewer.</li> <li>Expand the Type Libraries node.</li> <li>Double-click Microsoft Word  Object Library in the type libraries list.</li> <li>When the ITypeLib Viewer opens with the Word object library displayed, expand the node for coClass Application. Under the coClass Application node, you see ApplicationEvents and ApplicationEvents2. If you are viewing the Word 2002 object library, you also see ApplicationEvents3.</li> <li>Double-click ApplicationEvents2.</li> <li> In the right pane of the ITypeLib Viewer, locate the following UUID: uuid(000209FE-0000-0000-C000-000000000046) This UUID corresponds to the IID_ApplicationEvents2 variable that you declared in Appeventlistener.h. </li></ol>

back to the top

<div class="references_section">