Click here to Skip to main content
14,599,021 members

Writing an MS Word addin

Rate this:
4.76 (19 votes)
Please Sign up or sign in to vote.
4.76 (19 votes)
13 Apr 2003
Writing a Word Addin using COM and VB Macros


After having written about developing Office COM addins in an earlier article, I get a lot of mail from people trying to write Word addins. Through this article we will discuss common development issues regarding Word addins in general. First, we learn how to build a simple WORD 2000 ATL COM addin. Later in the article, we will get down to Word's VBA macro side of things, and write an addin that works for all versions of Word, independent of COM addin support.

I'm assuming you have read my previous article on Office addins and taken a look at the sample project. There are a lot of issues in addin development like adding custom menu/toolbars, handling events, property pages etc that are common for all Office addins, including Word. These have already been discussed in that article. Here we are going to write a Word 2000 COM addin, to begin with. Later, we'll delve into Office and VBA in general, and with respect to with C++ addins.

Writing a Word2000 Addin

To begin, create a new ATL COM Appwizard generated dll project called WordAddin. Next insert an ATL Simple Object called Addin, as in the previous article. Next use the Implement Interface ATL Wizard to implement _IDTExtensibility2. This, as you know, is the at the heart of COM addin support for all Office applications. Next, to program against Word, we need to import Word's typelib. That means, we need to import 3 interdependent typelibs. In your project's stdafx.h add the following code:

//for Office XP 
//C:\Program Files\\Common Files\\Microsoft Shared\\Office10\\MSO.DLL

#import "C:\\Program Files\\Microsoft Office\\Office\\mso9.dll" 
using namespace Office2000;

  "C:\\Program Files\\Common Files\\Microsoft Shared\\VBA\\VBA6\\VBE6EXT.olb" 
using namespace VBE6;

In your project's Addin.h file, towards the top, add:

//for Office XP
//C:\\Program Files\\Micorosft Office\\Office10\\MSWORD.olb

#import "C:\\Program Files\\Microsoft Office\\Office\\MSWORD9.olb" 
using namespace MSWord;

Make sure that you change the path to point to the correct locations of the files for your system.

The different locations for the #import statements is needed for the compiler to recognize everything, generate the correct set of wrappers, and compile and link correctly. Moving on, to register your addin with Word2000, add the following code to Addin .rgs registry script file (under FileView->Resource Files) and add the following to the end of the file.

              val FriendlyName = s 'WORD Custom Addin'
              val Description = s 'Word Custom Addin'
              val LoadBehavior = d '00000003'
              val CommandLineSafe = d '00000001'

Yes, we'd like our addin to be called 'Word Custom Addin' ('I love Addin', would have been too blatant!), and loaded when Word starts up. So what else is new? :)

If everything has gone right, you now have a working WORD addin to which you should add your own implementation code. By now you already know how to add buttons and menu items in your addin, property sheets etc; all that has been discussed in the previous article holds true. The only thing different in the Word Object Model, and from the code in the Outlook addin example, is that there is no ActiveExplorer object in Word, and you should get the CommandBars interface directly from Application, the topmost in the object model.

Handling Events

Probably in your addin, you'd also be interested in handling some of Word's events.A case in point is the Application objects DocumentOpen event, with DISPID=4, which is handled here. Word has a complex object model and you will find a host of other such events. If you use the good old OLE/COM Object Viewer to view msword9.olb, you'd find IDL like :


[id(0x00000003), helpcontext(0x00061a83)]
    void DocumentChange();
    [id(0x00000004), helpcontext(0x00061a84)]
    void DocumentOpen([in] Document* Doc);


As before we will use ATL's IDispEventSimpleImpl<> template class to implement our sink. For brevity, only the changes necessary to the earlier code has been mentioned.

extern _ATL_FUNC_INFO DocumentOpenInfo;

class ATL_NO_VTABLE CAddin : 
    public CComObjectRootEx,
    public CComCoClass,
    public ISupportErrorInfo,
    public IDispatchImpl,
    public IDispatchImpl<_IDTExtensibility2, &IID__IDTExtensibility2,  
    public IDispEventSimpleImpl<1,CAddin,     

void __stdcall DocumentOpen(IDispatchPtr ptr)
    CComQIPtr<_Document> spDoc(ptr);


CComPtr<MSWord::_Application> m_spApp;

DocumentOpenInfo is defined at the top of CAddin.cpp as


All that remains for us to do is to add the code to setup and break down the connection. Using the ATL template class, therefore all we have to do is call DispEventAdvise() and DispEventUnadvise(). Our CAddin's OnConnection() and OnDisconnection(), needless to say, is the right place for doing this.

CComQIPtr<_Application> spApp(Application);
m_spApp = spApp;
HRESULT hr = DispEventAdvise(m_spApp);
return hr;

and in OnDisconnection(),

m_spApp = NULL;

Now you have a working Word COM addin template, proudly under your belt. To this you should add your own implementation, error-handling routines etc. Moving on to something different, let's explore VBA side of WORD. Next, I'll discuss a very specific scenario where I use a mix of C++ code and VBA macros in my addin.

Macros and the Visual Basic Editor

I was working on a project, where the COM addin model of things suited us fine. Except the client had a large number of Word97 users, and Word97 has no support for COM addins, specifically the IDTExtensibility2 interface. Basically in my addin I needed to add a few custom menu items and buttons, clicking which usually meant displaying a couple of dialogs. Now, a COM addin would be perfect for Word2000 users. But was there some way we could make the addin Word97 compatible?

This leads us to Visual Basic for Applications(VBA). Most Office developers know that MS Office components and applications support a rich scripting object model and a scripting interface known as VBA. Before Office version 4, each application in the suite was very distinct. For developers, wasn't easy to create integrated solutions using multiple Office applications, because each application had a unique programming environment.

This problem was addressed through MS Visual Basic for Applications (VBA), which made it's debut in Office 95 - albeit, in a few applications. By Office97, every app in the suite supported standard VBA interfaces. The set of functions that a VBA routine, or macro, can use to control its host application is the same set of functions that the OLE Automation client can use to control the application externally, regardless of the programming language for the controller. Word 97 includes Visual Basic 5.0, a sophisticated development environment that is shared across Office applications: Word, Excel, PowerPoint, and Access.

In Word, VBA and Visual Basic goes beyond being merely a macro language—it is a full-featured programming development environment. The Visual Basic Editor (VBE) uses the familiar programming interface of Microsoft Visual Basic 4.0 as a base for creating and editing script code. Through VBA, Word supported everything from macros to addins to document templates. So what is a document template? A document template(*.dot) is simply a document with macro code (script) embedded in it. In Word, macros are persisted in documents and templates as Visual Basic modules. Although macros are ordinarily stored in the user's default template,, Word allows you store and use macros in any document or template. Moreover, any such document template in the Office installation's Startup folder, would be autorun.Additional templates and macros can be loaded using the Templates & Add-ins or Macros dialog box in the Tools menu. Macros and document templates (also supported for WordPerfect) can also be shared across users in a Workgroup.

What is also interesting is, MS Word97 onwards also supports a group of global macros that gets invoked with the host application. These AutoXXX macros like AutoExec(), AutoNew(),AutoOpen(),AutoClose() and AutoExit() gets executed along with the host application, just as their names suggest. This sounds most useful and it is.

How? If we were to create a document template, handle such Auto macros in it, and then create and destroy our addin (which is written as an ActiveX server) through VBA macros - then we should be on the home stretch. This is what IDTExtensibility2 does for COM addins - primarily a way to connect and disconnect to the topmost Application object. So how can we substitute something like this in our Word97 addin? Through document templates. Document templates, by themselves, can be described as VBA addins. Every document template is set up to interact with the Document object associated with the project through the ThisDocument property. We must also remember that all macros implicitly reference the Application object.

Back to the task at hand, suppose we were to write a document template and in it, add code to ourAutoExec() and AutoExit() handlers. In the handlers, we create and release our addin COM class object and subsequently call it's methods. Moreover, our ATL COM class should implement two methods, Init() and Uninit() through which the Application object is set in the C++ addin. Our macros ought to look like:

Dim o as Application
Dim obj as Object

Sub AutoExec()
Set obj = CreateObject("Word97Addin.Addin")
Set o = ThisDocument.Application
obj.Init o
End Sub

Sub AutoExit()
Set o = ThisDocument.Application
obj.Uninit o
Set obj = Nothing
Set o = Nothing
End Sub

We can choose to automatically load and unload our template by placing it in the Office's Startup folder.Similarly you can handle AutoClose(),AutoNew() and AutoOpen() macros, which are more document related. For the moment, since I'm handling all button/menu creation and events in my C++ COM object, the communication is unidirectional(i.e. macro->addin), but bidirectional communication is not too difficult.Suppose you have a macro defined in your template called "NewMacro"; one way to trigger this macro from a C++ addin is through Application::Run() or Application::RunOld(), depending on whether you need to pass any parameters. What is interesting is that, you can also trigger the macro through a button click, by setting the OnAction property of the CommandBarButton object of your button or menuitem.

// get CommandBarButton interface so we can specify button styles
CComQIPtr < Office::CommandBarButton> spCmdButton(spNewBar);
//set other button properties

This is just what I did for my project. We have a single solution, consisting of a dll and a dot file, that runs across all versions of Word - from 97 to XP, exposing and encapsulating most of it's functionilty through compiled C++ code. Unfortunately, this VBA support brings up the security issue, and in later versions of Office like XP, the user can determine the security level in macro execution context. Although this was a non-issue with us, you need to be aware.

All of what we have learnt so far. has been espoused in the accompanied VC++ 6.0 Universal Addin project, which I will briefly describe next.

Universal Addin

Universal Addin is a simple ATL/COM AppWizard generated dll project, to which I inserted an ATL COM IDispatch-based Simple Object called Addin. While the name sounds very pretentious, 'Universal' refers to it's ability to run across all versions of Word.

Image 1

What lends it such universality is the Word document template that is a part of the addin, and it's AutoXXX Macros. Our Addin class has two member methods Init() and Uninit() that take a single IDispatch* to the Application object. Our Uninit() implementation is very simple and we could have done without the IDispatchPtr parameter; might not be so for your implementation.In the project, we add a single button through the addin, clicking which triggers a VBA named macro, that in turn calls a method of our COM class. By all means, you can connect to CommandBarButtonEvents and write C++ code to handle button click, as done previously.

Out aim was to write an addin for Word, bypassing the the COM addin architecture and IDTExtensibility2.That concluded, all that remains for me to say is that whatever you can do with VBA, you can do from C++ and vice versa - the magic is in OLEAutomation.


Everything I know about Office development, I learnt at MSDN. You, too, can find a hoard of technical articles and short KB code snippets related to everything from Office development to COM and OLE Automation. MSDN rules - as we all know. :)

Thanks to Peter Hauptmann (a.k.a Peterchen) for his comments and suggestions.


  • First revision - 14th April, 2003.


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


About the Author

Amit Dey
Web Developer
India India
Amit Dey is a freelance programmer from Bangalore,India. Chiefly programming VC++/MFC, ATL/COM and PocketPC and Palm platforms. Apart from programming and CP, he is a self-taught guitar and keyboard player.

He can be contacted at

Comments and Discussions

GeneralRe: Unable to remove Menu Item from MSWord Pin
tartancli28-Jul-05 0:32
Membertartancli28-Jul-05 0:32 
GeneralRe: Unable to remove Menu Item from MSWord Pin
Trevor White26-Mar-08 0:48
MemberTrevor White26-Mar-08 0:48 
GeneralCustom Property Pin
UltraBob4-May-05 22:40
sussUltraBob4-May-05 22:40 
Generalcompilation errors - help Pin
rjnl20-Apr-05 10:38
Memberrjnl20-Apr-05 10:38 
GeneralCompilation produced 18 errors Pin
ajalilqarshi27-Jan-05 0:25
Memberajalilqarshi27-Jan-05 0:25 
GeneralRe: Compilation produced 18 errors Pin
Per R. Anderson12-Dec-06 18:17
MemberPer R. Anderson12-Dec-06 18:17 
QuestionHow can &quot;get_ActiveDocument&quot; under click button??? Pin
sony_synco14-Sep-04 12:00
Membersony_synco14-Sep-04 12:00 
AnswerRe: how to get a shape Pin
Amit Dey2-Sep-04 0:12
MemberAmit Dey2-Sep-04 0:12 
here's how it works:

<br />
CComPtr< MSWord::Shapes > spShapes;<br />
CComPtr< MSWord::Shape > spShape;<br />
//assume spDoc is ActiveDocument<br />
hr =  spDoc->get_Shapes(&spShapes); <br />
if(FAILED(hr))<br />
return hr;<br />
long nCount = 0;<br />
spShapes->get_Count(&nCount);<br />
float fWidth;<br />
for(int j=1;j<=nCount;j++)<br />
{<br />
  spShape = spShapes->Item(&CComVariant(j));<br />
<br />
  //show some MSWord::Shape properties	<br />
<br />
  spShape->get_Width(&fWidth); <br />
  CComBSTR bstrShpName;<br />
  spShape->get_Name(&bstrShpName); <br />
  ATLTRACE("\nWidth: %f %s ",fWidth,W2T(bstrShpName));<br />
  spShape.Detach(); <br />
}<br />
<br />
spShapes.Detach(); <br />
<br />
 <br />

Wink | ;)

I come in peace. But what about your snot-rag?

Amit Dey

GeneralGet Document Content under click button Pin
Anonymous27-Aug-04 10:52
MemberAnonymous27-Aug-04 10:52 
GeneralRe: Get Document Content under click button Pin
GnanaprakashJebaraj16-Jun-05 3:31
MemberGnanaprakashJebaraj16-Jun-05 3:31 
GeneralRe: Get Document Content under click button Pin
sivanagaraju_14316-Apr-06 22:23
Membersivanagaraju_14316-Apr-06 22:23 
Questionhow to get a shape Pin
thmarx18-Aug-04 2:49
Memberthmarx18-Aug-04 2:49 
QuestionHow to Intercept events in a word add-in Pin
squaredchlee11-Jul-04 21:28
Membersquaredchlee11-Jul-04 21:28 
Questionhow to handle events in Outlook2000 button Pin
softp_vc11-May-04 0:18
Membersoftp_vc11-May-04 0:18 
GeneralWord doesn't see my addin Pin
cokebaby28-Apr-04 21:31
Membercokebaby28-Apr-04 21:31 
GeneralRe: Word doesn't see my addin Pin
Jupiler9-Jun-04 3:23
MemberJupiler9-Jun-04 3:23 
GeneralRe: Word doesn't see my addin Pin
Andrew Hore8-Dec-04 3:54
MemberAndrew Hore8-Dec-04 3:54 
GeneralRe: Word doesn't see my addin Pin
pidstuliu26-Jun-06 15:49
Memberpidstuliu26-Jun-06 15:49 
Generaladd menuItem to word Pin
jake_ss26-Apr-04 5:37
sussjake_ss26-Apr-04 5:37 
Generaladd menuItem to word Pin
jake_ss26-Apr-04 5:36
sussjake_ss26-Apr-04 5:36 
GeneralRe: add menuItem to word Pin
mandanani20-Jul-05 23:35
Membermandanani20-Jul-05 23:35 
GeneralRe: add menuItem to word Pin
robert752824-Jun-07 16:24
Memberrobert752824-Jun-07 16:24 
GeneralCompile error Pin
youth2121-Apr-04 5:21
sussyouth2121-Apr-04 5:21 
GeneralRe: Compile error Pin
youth2121-Apr-04 5:32
sussyouth2121-Apr-04 5:32 
GeneralRe: Compile error Pin
Amit Dey28-Apr-04 5:13
MemberAmit Dey28-Apr-04 5:13 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Posted 13 Apr 2003


87 bookmarked