C++ Builder Developer's Journal / Word 97 OLE Automation

February 1999

Word 97 OLE Automation

Object Linking and Embedding (OLE) provides us a simple way to share components between applications. It gives us the ability to use different object-based services in order to enable a full integration between components. OLE 2.0 introduced more powerful features such as OLE Containers and OLE Automation. In this article, we'll explain how to use OLE Automation to execute different Word 97 tasks from Borland C++Builder, like opening, closing, or printing files.

The Variant Class

In order to connect to Word 97, we'll use the Variant class. The Variant class can represent different dynamically changing values, such as strings, integers or OLE Automation objects. Now, we can open the Word 97 application (don't forget to include the <comobj.hpp> header required for using OLE Automation):

Variant wordApp;
if (wordApp.IsEmpty())
{
    wordApp=Variant::CreateObject("Word.Application");
}
else
{
    wordApp=GetActiveOleObject("Word.Application");
}
if (wordApp.IsEmpty())
{
    ShowMessage("Unable to find Word application.");
    return;
}

The CreateObject() method, executes Word if it's not already opened. If it is, it just creates a new window using GetActiveOleObject(). Once we're connected, the Variant class presents us three important methods: OleProcedure(), OlePropertyGet() and OlePropertySet(). For example, if we want to make Word 97 visible, we can just use the property Visible and set it to true.


    wordApp.OlePropertySet("Visible", (Variant) true);

Creating the application

First, we'll create a simple form. Choose File | New Application from the menu. Place five buttons on the form and call them Connect, Open, Save, Print, and Insert Table. Double-click the Connect button and insert the previous line of code into it. Compile the application and test it.

Opening / Saving a file

In order to open or save a file, we'll use the methods provided by the Documents object. Here's how to derive Documents from the wordApp:

Variant wordDocuments = wordApp.OlePropertyGet("Documents");

If you check the VBA help file that comes with Word 97, you'll see that the Documents object has five methods: Add(), Close(), Item(), Open(), and Save(). Here, we'll use the Open() method using the following syntax Open(FileName). For example:

// opens the "config.sys" file
wordDocuments.OleProcedure("Open", (Variant) 
	"c:\\config.sys");

The Save() method is even easier:

wordDocuments.OleProcedure("Save");

Printing a file

As we saw, the Documents object doesn't give us a print method but the variant wordApp that we already created does. Now, using PrintOut() we'll print the current document:

wordApp.OleProcedure("PrintOut");

Insert a table

Let's suppose we want to open a new document and insert a table (3 rows and 5 columns). The AciveDocuments.Tables object contains the method Add() that we'll use in this example. Here's the syntax:


Add(Range As Range, NumRows As Long, NumColumns As Long)

Now you can easily insert the table as follows:

// creates a new document
wordDocuments.OleProcedure("Add");
Variant wordActiveDocument = 
	wordApp.OlePropertyGet("ActiveDocument");
Variant wordTables = 
	wordActiveDocument.OlePropertyGet("Tables");
Variant wordSelection = 
	wrdApp.OlePropertyGet("Selection");
Variant Range = wordSelection.OlePropertyGet("Range");
// inserts the table
wordTables.OleProcedure("Add", Range, (Variant) 3, 
	(Variant) 5);

Creating the table wasn't that difficult, but how can we now insert our own value in the 2^nd row and the 3^rd column for example. Again, we'll use the Tables object but this time Tables.Cell.Range.Text:

Variant wordTable1 = wordTables.OleFunction("Item", 
	(Variant) 1);
Variant wordCell = wordTable1.OleFunction("Cell", 
	(Variant) 2, (Variant) 3 );
Variant wordRange = wordCell.OlePropertyGet("Range");
wordRange.OlePropertySet("Text", (Variant) "We are at 2/3");

Conclusion

As we saw in this article, using OLE isn't difficult when we know the right object and method to use. The VBA help file contains the full list of all Word functions (you can find it in \Microsoft Office\Office\Vbawrd8.hlp). OLE gives us the flexibility to execute almost any Word task without even using Word. Plus, all other Microsoft Office applications like Excel, PowerPoint, or Access also include OLE Automation. The power is yours...