Microsoft Word Automation Class

CodeGuru content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

Introduction

Often, the main challenge in developing C++ automation solutions for Microsoft Office is the lack of detailed technical documentation for Office’s OLE interface. At the same time, ample automation information for Visual Basic applications can be acquired by using Office macros and the Office Help Wizard. It would be natural to come with a tool that can be used to “translate” or “convert” Office’s macros into code executable from C++. This approach was previously implemented in an MSVC Excel automation project and is described in the recent article on CodeGuru (see “Microsoft Excel Automation Class” by V. Golovlev).

In this article, the approach is modified for executing Microsoft Word functions from an MSVC application. The CWordAutomation class that implements this approach includes a small collection of OLE functions and also contains examples of code for some MS Office operations. Also, a CEzWordAutomation wrapper class is provided; it exposes a set of methods from CWordAutomation to perform basic access to MS Word documents.

The MSWordDemo project provides an example of using CWordAutomation and CEzWordAutomation to read and write text from and to MS Word documents, open and save Word files, and use the Word spell function to check word spelling in an MSVC application.

The CWordAutomation has two groups of methods: 1) to access OLE interface, and 2) to implement selected macros. The most essential methods from the first group include WordDispatch(…), AddArgumentCString(…), AddArgumentInt2(…), and ClearAllArgs(). The second group includes an example of implementating Word macros to create a new Word document, adding and reading text from the Word document, and opening/saving Word files:

• CreateBlankDocument()
• AppendText(CString szText)
• GetLine(int nLine)
• OpenWordFile(CString szFileName)
• SaveWordFileAs(CString szFileName)
• and some others.

The MSWordDemo project gives an example of using CWordAutomation and CEzWordAutomation. In this project, a Word document is viewed as a collection of lines (strings) that can be read from or written to the document. Each Word line can be accessed in the document by its line number (see CWordAutomation::GetLine(int nLine)). The total number of lines in the document is retrieved by GetLinesCount(). The user can add a new string (line) to the document by using the AppendText(…) method. The new text is appended at the end of the document. To move a large amount of data and copy text between Word documents, the CopyLinesToClipboard(…) method is available. Text is copied to a clipboard and subsequently can be pasted into the document by using the PasteText(…) method.

A Word application can be started in one of two modes: with the user interface exposed (bVisible = TRUE) or hidden (bVisible = FALSE). In the first mode, the document and Word interface are visible and available to the user. In the second mode (bVisible = FALSE), Word runs in the background with no interface exposed, but Word functions can be executed by MSVC code.

Adding a Word Automation Function to a MSVC Project

Add CWordAutomation and CEzWordAutomation classes to your project (see also “Microsoft Excel Automation Class” on how to add automation classes to the project). To start a new Word document, use this code in your application:

CEzWordAutomation MsWord;

To start Word in the background with no interface exposed to the user:

To release the document and close the Word application, call:

MsWord.ReleseWord.

To open a Word file and get/create szFileName, call:

MsWord.OpenWordFile(szFileName);

Also, see the WordDemo project for examples of implementating the CWordAutomation and CEzWordAutomation classes.

The WordDemo project provides examples of using the CWordAutomation and CEzWordAutomation classes to start a new Word document and add new text to the document by entering a single line (AppendText(…)) or by copying multiple lines by the copy/paste clipboard function. Other examples include methods to open and save Word files. Also included in this project is an example of using Word’s spell engine to check word spelling from a C++ application.

To run the WordDemo application, Microsoft Word must be installed on your computer!

To run the demo program, compile and run the project.The WordDemo interface has two sections: one to demonstrate Word functions and the other to demonstrate spell checking using the Word speller:

Functions of the DemoProject Buttons

• “Open New Word Doc”: Opens a new Word document and enters text using the AppendText(…) method. The Word interface is visible.
• “Paste to Word Doc”: Opens a new Word document and enters text using clipboard functions CopyTextToClipboard(…) and PasteText(…). The Word interface is visible.
• “Save Word File”: start Word in background (i.e., interface is not visible), enter text to the document, open file dialog and save Word file.
• “Open Word File”: Starts a Word application, opens file dialog and the Word file. The Word interface is visible.
• “Get Text”: Starts a Word application in the background, opens the file dialog, reads the number of lines in the Word file selected by user, reads the first and last lines in the file, releases the Word application, and reports the number of lines in the file and contents of the first and last line to the user.
• “Exit”: Releases WordDemo.
• “Spell check”: Uses Word’s spell engine to check spelling of the word the user entered. Word is started in the background mode after the user enters the word and clicks the “Check spelling” button. If Word’s speller reports one or more alternative spellings, the very first entry from the collection of the alternative spellings replaces the word in the Edit box. After completion, the Word application is released.

Writing Code to Add a New Word Function

The first step is to write a macro that performs the user’s function. For instance, the following macro returns the first entry from a collection of alternative spellings for the user’s word szUserWord:

szNewSpelling = Application.GetSpellingSuggestions(Word:=
   szUserWord).Item(Index:=1).Name

Note: To use this in MSVC method, the parameters MUST be named whenever possible. In a VB project, this macro works just fine:

Application.GetSpellingSuggestions(szUserWord).Item(1)

But, to use it in MSVC, it has to be used with all parameters spelled out:

Application.GetSpellingSuggestions(Word:=
   szUserWord).Item(Index:=1).Name

The next step is to add a new method to the CWordAutomation class and write the code. Each macro object, for instance MyMacroObject, is called in MSVC by a block of code as shown in the following code snippet:

{ClearAllArgs();
if (!WordInvoke(vargParentObject.pdispVal,
   L" MyMacroObject ", &vargMyChildObject, DISPATCH_METHOD, 0))
   return FALSE;}

Observe the use of vargParentObject B and vargMyChildObject here. In this example, MyMacroObject is the child of the ParentObject, and it has also its own child object MyChildObject: ParentObject.MyMacroObject.MyChildObject

If MyMacroObject requires a parameter to be used: MyParameter:=wdParamValue, the MSVC code has to be modified to this:

{ClearAllArgs();
AddArgumentInt2(L" MyParameter ", 0, wdParamValue);
if (!WordInvoke(vargParentObject.pdispVal, L" MyMacroObject ",
   &vargMyChildObject, DISPATCH_METHOD, 0))B return FALSE;}

In the above speller’s example, the macro uses four objects. The corresponding code will consist of three blocks of {ClearAllArgs… WordInvoke}(in other words, N-1 of the number of objects used, see CWordAutomation::SpellWord(CString szWord) for details). If the macro returns a value, that value can be retrieved from the VARIANTARG returned by the last WordInvoke(…) call. To see a detailed example of retrieving value from a macro, please refer to the CWordAutomation::GetLine(int nLine) method in the MSWordDemo project.

Additional examples of MSVC codes for Office macros can be found in discussions posted on CodeGuru for “Microsoft Excel Automation Class.”

The last step is to add the corresponding new method to EzWordAutomation. In most cases. it consists of a single line of code (see EzWordAutomation methods).

Thank you! Your comments are highly valuable!