Programming with Microsoft Visual C++.NET 6ed [Electronic resources] نسخه متنی

The MFC Application Wizard did most of the work of setting up the document as an Automation component. In the derived application class CEx23cApp, it generated a data member for the component, as shown here:

public:
COleTemplateServer m_server;

The MFC COleTemplateServer class is derived from COleObjectFactory. It is designed to create a COM document object when a client calls IClassFactory::CreateInstance. The class ID comes from the global clsid variable defined in

Ex23c.cpp . The human-readable program ID (Ex23c.Document) comes from the IDR_MAINFRAME string resource.

In the InitInstance function (in

Ex23c.cpp ), the MFC Application Wizard generated the following code, which connects the component object (the document) to the application's document template:

 CSingleDocTemplate* pDocTemplate;
pDocTemplate = new CSingleDocTemplate(
IDR_MAINFRAME,
RUNTIME_CLASS(CEx23cDoc),
RUNTIME_CLASS(CMainFrame),     // main SDI frame window
RUNTIME_CLASS(CEx23cView));
AddDocTemplate(pDocTemplate);
 
m_server.ConnectTemplate(clsid, pDocTemplate, TRUE);

Now all the plumbing is in place for COM and the framework to construct the document, together with the view and frame. When the objects are constructed, however, the main window is not made visible. That's your job. You must write a method that shows the window.

The following UpdateRegistry call from the InitInstance function updates the Windows Registry with the contents of the project's IDR_MAINFRAME string resource:

m_server.UpdateRegistry(OAT_DISPATCH_OBJECT);

The following dispatch map in the

Ex23cDoc.cpp file shows the properties and methods of the CEx23cDoc class. Note that the Figure property is an indexed property that the Add Property Wizard can generate if you specify a parameter. Later, you'll see the code you have to write for the GetFigure and SetFigure functions.

BEGIN_DISPATCH_MAP(CEx23cDoc, CDocument)
DISP_PROPERTY_NOTIFY_ID(CEx23cDoc, "Time", 
dispidTime, m_time, OnTimeChanged, VT_DATE)
DISP_FUNCTION_ID(CEx23cDoc, "ShowWin", 
dispidShowWin, ShowWin, VT_EMPTY, VTS_NONE)
DISP_FUNCTION_ID(CEx23cDoc, "CreateAlarm", 
dispidCreateAlarm, CreateAlarm, VT_DISPATCH, VTS_DATE)
DISP_FUNCTION_ID(CEx23cDoc, "RefreshWin", 
dispidRefreshWin, RefreshWin, VT_EMPTY, VTS_NONE)
DISP_PROPERTY_PARAM_ID(CEx23cDoc, "Figure", 
dispidFigure, GetFigure, SetFigure, VT_VARIANT, VTS_I2)
END_DISPATCH_MAP()

The ShowWin and RefreshWin member functions aren't very interesting, but the CreateAlarm method is worth a close look. Here's the corresponding CreateAlarm member function:

IDispatch* CEx23cDoc::CreateAlarm(DATE time)
{
AFX_MANAGE_STATE(AfxGetAppModuleState());
TRACE("Entering CEx23cDoc::CreateAlarm, time = %f\n", time);
// OLE deletes any prior CAlarm object
m_pAlarm = new CAlarm(time);
return m_pAlarm->GetIDispatch(FALSE);   // no AddRef here
}

We've chosen to have the component create an alarm object when a controller calls CreateAlarm. CAlarm is an Automation component class that we've generated with the Add Class Wizard. It is not COM-creatable, which means there's no IMPLEMENT_OLECREATE macro and no class factory. The CreateAlarm function constructs a CAlarm object and returns an IDispatch pointer. (The FALSE parameter for CCmdTarget::GetIDispatch means that the reference count is not incremented; the CAlarm object already has a reference count of 1 when it is constructed.)

The CAlarm class is declared in

Alarm.h as follows:

#pragma once
// CAlarm command target
class CAlarm : public CCmdTarget
{
DECLARE_DYNAMIC(CAlarm)
public:
CAlarm(DATE time);
virtual ~CAlarm();
virtual void OnFinalRelease();
DATE m_time;
protected:
DECLARE_MESSAGE_MAP()
DECLARE_DISPATCH_MAP()
DECLARE_INTERFACE_MAP()
void OnTimeChanged(void);
enum 
{
dispidTime = 1
};
};

Notice the absence of the DECLARE_DYNCREATE macro.

Alarm.cpp contains a dispatch map, as follows:

BEGIN_DISPATCH_MAP(CAlarm, CCmdTarget)
DISP_PROPERTY_NOTIFY_ID(CAlarm, "Time", 
dispidTime, m_time, OnTimeChanged, VT_DATE)
END_DISPATCH_MAP()

Why do we have a CAlarm class? We could have added an AlarmTime property in the CEx23cDoc class instead, but then we would have needed another property or method to turn the alarm on and off. By using the CAlarm class, what we're really doing is setting ourselves up to support multiple alarms—a collection of alarms.

To implement an Automation collection, we can write another class, CAlarms, that contains the methods Add, Remove, and Item. Add and Remove are self-explanatory; Item returns an IDispatch pointer for a collection element identified by an index, numeric, or some other key. We can also implement a read-only Count property that returns the number of elements. The document class (which owns the collection) will have an Alarms method with an optional VARIANT parameter. If the parameter is omitted, the method will return the IDispatch pointer for the collection. If the parameter specifies an index, the method will return an IDispatch pointer for the selected alarm.

The Figure property is an indexed property, which makes it interesting. The Figure property represents the four figures on the clock face—XII, III, VI, and IX. It's a CString array, so we can use Roman numerals. Here's the declaration in

Ex23cDoc.h :

public:
CString m_strFigure[4];

And here are the GetFigure and SetFigure functions in

Ex23cDoc.cpp :

VARIANT CEx23cDoc::GetFigure(SHORT n)
{
AFX_MANAGE_STATE(AfxGetAppModuleState());
TRACE("Entering CEx23cDoc::GetFigure -- n = %d m_strFigure[n] = %s\n",
n, m_strFigure[n]);
return COleVariant(m_strFigure[n]).Detach();
}
void CEx23cDoc::SetFigure(SHORT n, VARIANT FAR& newVal)
{
AFX_MANAGE_STATE(AfxGetAppModuleState());
TRACE("Entering CEx23cDoc::SetFigure -- n = %d, vt = %d\n", n, 
newVal.vt);
COleVariant vaTemp;
vaTemp.ChangeType(VT_BSTR, (COleVariant*) &newVal);
m_strFigure[n] = vaTemp.bstrVal; // converts double-to-single
SetModifiedFlag();
}

These functions tie back to the DISP_PROPERTY_PARAM macro in the CEx23cDoc dispatch map. The first parameter is the index number, specified as a short integer by the last macro parameter. Property indexes don't have to be integers, and the index can have several components (row and column numbers, for example). The ChangeType call in SetFigure is necessary because the controller might otherwise pass numbers instead of strings.

You've just seen collection properties and indexed properties. What's the difference? A controller can't add or delete elements of an indexed property, but it can add elements to a collection and it can delete elements from a collection.

What draws the clock face? As you might expect, it's the OnDraw member function of the view class. This function uses GetDocument to get a pointer to the document object, and then it accesses the document's property data members and method member functions.

The Excel macro code is shown here:

Dim Clock As Object
Dim Alarm As Object
Sub LoadClock()
Set Clock = CreateObject("Ex23c.Document")
Range("A3").Select
n = 0
Do Until n = 4
Clock.figure(n) = Selection.Value
Selection.Offset(0, 1).Range("A1").Select
n = n + 1
Loop
RefreshClock
Clock.ShowWin
End Sub
Sub RefreshClock()
Clock.Time = Now()
Clock.RefreshWin
End Sub
Sub CreateAlarm()
Range("E3").Select
Set Alarm = Clock.CreateAlarm(Selection.Value)
RefreshClock
End Sub
Sub UnloadClock()
Set Clock = Nothing
End Sub

Notice the Set Alarm statement in the CreateAlarm macro. It calls the CreateAlarm method to return an IDispatch pointer, which is stored in an object variable. If the macro is run a second time, a new alarm is created, but the original one is destroyed because its reference count goes to 0.

The Ex23d Example: An Automation Client

So far, you've seen C++ Automation component programs. Now you'll see a C++ Automation client program that runs all the previous components and also controls Excel. The Ex23d program was originally generated by the MFC Application Wizard, but without any COM options. It was easier to add the COM code than it would have been to rip out the component-specific code. If you use the MFC Application Wizard to build such an Automation controller, add the following line at the end of

StdAfx.h :

#include <afxdisp.h>

Then add this call at the beginning of the application's InitInstance function:

AfxOleInit();

To prepare Ex23d, open the \vcppnet\Ex23d\

Ex23d.sln solution and do the build. Run the application, and you'll see a standard SDI application with a menu structure similar to that shown in Figure 23-5.

Figure 23-5: A sample menu structure for a standard SDI application.

If you've built and registered all the components, you can test them from Ex23d. Notice that the DLL doesn't have to be copied to the \Winnt\System32 directory because Windows finds it through the Registry. For some components, you'll have to watch the Debug window to verify that the test results are correct. The program is reasonably modular. Menu commands and update command user interface events are mapped to the view class. Each component object has its own C++ controller class and an embedded data member in

Ex23dView.h . We'll look at each part separately after we delve into type libraries.

Type Libraries and IDL Files

I've told you that type libraries aren't necessary for the MFC IDispatch implementation, but Visual C++ .NET has been quietly generating and updating type libraries for all your components. What good are these type libraries? VBA can use a type library to browse your component's methods and properties, and it can use the type library for improved access to properties and methods—a process called early binding (described later in this chapter). But we're building a C++ client program here, not a VBA program. It so happens that the Add Class Wizard can read a component's type library and use the information to generate C++ code for the client to use to "drive" an Automation component.

When you added properties and methods to your component classes, the Add Method Wizard and the Add Property Wizard updated the project's IDL file. This file is a text file that describes the component in IDL. (Your GUID will be different if you used the MFC Application Wizard to generate this project.) Here's the IDL file for the bank component:

// Ex23a.idl : type library source for Ex23a.exe
// This file will be processed by the MIDL compiler to produce the
// type library (Ex23a.tlb).
#include "olectl.h"
[ uuid(60BCA7D2-14D1-4832-A278-50670CD9975E), version(1.0) ]
library Ex23a
{
importlib("stdole32.tlb");
importlib("stdole2.tlb");
//  Primary dispatch interface for CEx23aDoc    
[ uuid(1F013122-EA3D-414F-B58F-5A31A64EA5D5) ]
dispinterface IEx23a
{
properties:            
methods:
};
//  Class information for CEx23aDoc    
[ uuid(5EE5C98C-5CCF-46F4-9E95-17BC06237D8B) ]
coclass Ex23a
{
[default] dispinterface IEx23a;
};
//  Primary dispatch interface for Bank        
[ uuid(8BAD2B0C-62CC-4952-811C-C736DA06858E) ]
dispinterface IBank
{
properties:
[id(3), helpstring("property Balance")] DOUBLE Balance;
methods:
[id(1), helpstring("method Withdrawal")] 
DOUBLE Withdrawal(DOUBLE dAmount);
[id(2), helpstring("method Deposit")] 
void Deposit(DOUBLE dAmount);
};
//  Class information for Bank
[ uuid(3EC6FA59-9F9F-4619-9F62-BA5FE37176F0) ]
coclass Bank
{
[default] dispinterface IBank;
};
};

The IDL file has a unique GUID type library identifier, 60BCA7D2-14D1-4832-A278-50670CD9975E, that completely describes the bank component's properties and methods under a dispinterface named IBank. In addition, it specifies the dispinterface GUID, 8BAD2B0C-62CC-4952-811C-C736DA06858E, which is the same GUID that's in the interface map of the CBank class listed earlier. You'll see the significance of this GUID later in this chapter. The CLSID, 3EC6FA59-9F9F-4619-9F62-BA5FE37176F0, is what a VBA browser can actually use to load your component.

Anyway, when you build your component project, Visual Studio .NET invokes the MIDL utility, which reads the IDL file and generates a binary TLB file in your project's debug or release subdirectory. By default, the type information is also included as part of the binary. When you develop a C++ client program, you can ask the Add Class Wizard to generate a driver class from the component project's TLB file.

To actually do this, you choose Add Class from the Project menu and select the MFC Class From TypeLib template. You navigate to the component project's TLB file, and then the Add Class Wizard shows you a dialog box similar to the one shown here:

IBank is the dispinterface specified in the IDL file. You can keep this name for the class if you want, and you can specify the H filename. If a type library contains several interfaces, you can make multiple selections. You'll see the generated controller classes in the sections that follow.

The Controller Class for Ex23a.exe

The Add Class From Typelib Wizard generated the IBank class (derived from COleDispatchDriver) shown in the following listing. Look closely at the member function implementations. Note the first parameters of the GetProperty, SetProperty, and InvokeHelper function calls. These are hard-coded DISPIDs for the component's properties and methods, as determined by the component's dispatch map sequence.

BankDriver.h

class CBank : public COleDispatchDriver
{
public:
CBank(){} // Calls COleDispatchDriver default constructor
CBank(LPDISPATCH pDispatch) : COleDispatchDriver(pDispatch) {}
CBank(const CBank& dispatchSrc) : COleDispatchDriver(dispatchSrc) {}
// Attributes
public:
// Operations
public:
// IBank methods
public:
double Withdrawal(double dAmount)
{
double result;
static BYTE parms[] = VTS_R8 ;
InvokeHelper(0x1, DISPATCH_METHOD, VT_R8, (void*)&result, 
parms, dAmount);
return result;
}
void Deposit(double dAmount)
{
static BYTE parms[] = VTS_R8 ;
InvokeHelper(0x2, DISPATCH_METHOD, VT_EMPTY, NULL, 
parms, dAmount);
}
// IBank properties
public:
double GetBalance()
{
double result;
GetProperty(0x3, VT_R8, (void*)&result);
return result;
}
void SetBalance(double propVal)
{
SetProperty(0x3, VT_R8, propVal);
}
};

The CEx23dView class has a data member m_bank of class IBank. The CEx23dView member functions for the Ex23a.Bank component are listed below. They are hooked up to options on the Ex23d main menu. Of particular interest is the OnBankoleLoad function. The COleDispatchDriver::CreateDispatch function loads the component program (by calling CoGetClassObject and IClassFactory::CreateInstance) and then calls QueryInterface to get an IDispatch pointer, which it stores in the object's m_lpDispatch data member. The COleDispatchDriver::ReleaseDispatch function, called in OnBankoleUnload, calls Release on the pointer.

void CEx23dView::OnBankoleLoad()
{
if(!m_bank.CreateDispatch("Ex23a.Bank")) {
AfxMessageBox("Ex23a.Bank component not found");
return;
}
}
void CEx23dView::OnUpdateBankoleLoad(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_bank.m_lpDispatch == NULL);
}
void CEx23dView::OnBankoleTest()
{
m_bank.Deposit(20.0);
m_bank.Withdrawal(15.0);
TRACE("new balance = %f\n", m_bank.GetBalance());
}
void CEx23dView::OnUpdateBankoleTest(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_bank.m_lpDispatch != NULL);
}
void CEx23dView::OnBankoleUnload()
{
m_bank.ReleaseDispatch();
}
void CEx23dView::OnUpdateBankoleUnload(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_bank.m_lpDispatch != NULL);
}

The Controller Class for Ex23b.dll

The following listing shows the class header file generated by the Add Class From Typelib Wizard:

AutoDriver.h

// Machine generated IDispatch wrapper class(es) created with 
// Add Class from Typelib Wizard
// CEx23bAuto wrapper class
class CEx23bAuto : public COleDispatchDriver
{
public:
CEx23bAuto(){} // Calls COleDispatchDriver default constructor
CEx23bAuto(LPDISPATCH pDispatch) : COleDispatchDriver(pDispatch) {}
CEx23bAuto(const CEx23bAuto& dispatchSrc) :  
COleDispatchDriver(dispatchSrc) {}
// Attributes
public:
// Operations
public:
// IEx23bAuto methods
public:
BOOL DisplayDialog()
{
BOOL result;
InvokeHelper(0x3, DISPATCH_METHOD, VT_BOOL, 
(void*)&result, NULL);
return result;
}
// IEx23bAuto properties
public:
long GetLongData()
{
long result;
GetProperty(0x1, VT_I4, (void*)&result);
return result;
}
void SetLongData(long propVal)
{
SetProperty(0x1, VT_I4, propVal);
}
VARIANT GetTextData()
{
VARIANT result;
GetProperty(0x2, VT_VARIANT, (void*)&result);
return result;
}
void SetTextData(const VARIANT& propVal)
{
SetProperty(0x2, VT_VARIANT, &propVal);
}
};

Notice that each property requires separate Get and Set functions in the client class, even though a data member in the component represents the property.

The view class header has a data member m_auto of class CEx23bAuto. Here are some DLL-related command handler member functions from

Ex23dView.cpp :

void CEx23dView::OnDlloleGetdata()
{
m_auto.DisplayDialog();
COleVariant vaData = m_auto.GetTextData();
ASSERT(vaData.vt == VT_BSTR);
CString strTextData(vaData.bstrVal);
long lData = m_auto.GetLongData();
TRACE("CEx23dView::OnDlloleGetdata -- long = %ld, text = %s\n",
lData, strTextData);
}
void CEx23dView::OnUpdateDlloleGetdata(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_auto.m_lpDispatch != NULL);
}
void CEx23dView::OnDlloleLoad()
{
if(!m_auto.CreateDispatch("Ex23b.Ex23bAuto")) {
AfxMessageBox("Ex23b.Ex23bAuto component not found");
return;
}
COleVariant va("test");
m_auto.SetTextData(va);  // testing
m_auto.SetLongData(79);  // testing
// verify dispatch interface
// {125FECB2-734D-49FD-95C7-FE44B77FDE2C}
static const IID IID_IEx23bAuto =
{ 0x125FECB2, 0x734D, 0x49FD, { 0x95, 0xC7, 0xFE, 
0x44, 0xB7, 0x7F, 0xDE, 0x2C } };
LPDISPATCH p;
HRESULT hr = m_auto.m_lpDispatch->QueryInterface(IID_IEx23bAuto, 
(void**) &p);
TRACE("OnDlloleLoad -- QueryInterface result = %x\n", hr);
p->Release();
}
void CEx23dView::OnUpdateDlloleLoad(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_auto.m_lpDispatch == NULL);
}
void CEx23dView::OnDlloleUnload()
{
m_auto.ReleaseDispatch();
}
void CEx23dView::OnUpdateDlloleUnload(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_auto.m_lpDispatch != NULL);
}

The Controller Class for Ex23c.exe

The following code shows the headers for the CEx23c and CAlarm classes, which drive the Ex23c Automation component:

ClockDriver.h

// Machine generated IDispatch wrapper class(es) created with 
// Add Class from Typelib Wizard
// CEx23c wrapper class
class CEx23c : public COleDispatchDriver
{
public:
CEx23c(){} // Calls COleDispatchDriver default constructor
CEx23c(LPDISPATCH pDispatch) : COleDispatchDriver(pDispatch) {}
CEx23c(const CEx23c& dispatchSrc) : 
COleDispatchDriver(dispatchSrc) {}
// Attributes
public:
// Operations
public:
// IEx23c methods
public:
void ShowWin()
{
InvokeHelper(0x2, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}
LPDISPATCH CreateAlarm(DATE Time)
{
LPDISPATCH result;
static BYTE parms[] = VTS_DATE ;
InvokeHelper(0x3, DISPATCH_METHOD, VT_DISPATCH, 
(void*)&result, parms, Time);
return result;
}
void RefreshWin()
{
InvokeHelper(0x4, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}
VARIANT get_Figure(short n)
{
VARIANT result;
static BYTE parms[] = VTS_I2 ;
InvokeHelper(0x5, DISPATCH_PROPERTYGET, VT_VARIANT, 
(void*)&result, parms, n);
return result;
}
void put_Figure(short n, VARIANT newValue)
{
static BYTE parms[] = VTS_I2 VTS_VARIANT ;
InvokeHelper(0x5, DISPATCH_PROPERTYPUT, VT_EMPTY, 
NULL, parms, n, &newValue);
}
// IEx23c properties
public:
DATE GetTime()
{
DATE result;
GetProperty(0x1, VT_DATE, (void*)&result);
return result;
}
void SetTime(DATE propVal)
{
SetProperty(0x1, VT_DATE, propVal);
}
};

CAlarm.h

class CAlarm : public COleDispatchDriver
{
public:
CAlarm(){} // Calls COleDispatchDriver default constructor
CAlarm(LPDISPATCH pDispatch) : COleDispatchDriver(pDispatch) {}
CAlarm(const CAlarm& dispatchSrc) : 
COleDispatchDriver(dispatchSrc) {}
// Attributes
public:
// Operations
public:
// IAlarm methods
public:
// IAlarm properties
public:
DATE GetTime()
{
DATE result;
GetProperty(0x1, VT_DATE, (void*)&result);
return result;
}
void SetTime(DATE propVal)
{
SetProperty(0x1, VT_DATE, propVal);
}
};

Of particular interest is the CEx23c::CreateAlarm member function in

ClockDriver.h . This function can be called only after the clock object (document) has been constructed. It causes the Ex23c component to construct an alarm object and return an IDispatch pointer with a reference count of 1. The COleDispatchDriver::AttachDispatch function connects that pointer to the client's m_alarm object, but if that object already has a dispatch pointer, the old pointer is released. That's why, if you watch the Debug window, you'll see that the old Ex23c instance exits immediately after you ask for a new instance. You'll have to test this behavior with the Excel driver because Ex23d disables the Load menu command when the clock is running.

The view class has the data members m_clock and m_alarm. Here are the view class command handlers:

void CEx23dView::OnClockoleCreatealarm()
{
CAlarmDialog dlg;
if (dlg.DoModal() == IDOK) {
COleDateTime dt(2002, 12, 23, dlg.m_nHours, dlg.m_nMinutes, 
dlg.m_nSeconds);
LPDISPATCH pAlarm = m_clock.CreateAlarm(dt);
m_alarm.AttachDispatch(pAlarm);  // releases prior object!
m_clock.RefreshWin();
}
}
void CEx23dView::OnUpdateClockoleCreatealarm(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_clock.m_lpDispatch != NULL);
}
void CEx23dView::OnClockoleLoad()
{
if(!m_clock.CreateDispatch("Ex23c.Document")) {
AfxMessageBox("Ex23c.Document component not found");
return;
}
m_clock.put_Figure(0, COleVariant("XII"));
m_clock.put_Figure(1, COleVariant("III"));
m_clock.put_Figure(2, COleVariant("VI"));
m_clock.put_Figure(3, COleVariant("IX"));
OnClockoleRefreshtime();
m_clock.ShowWin();
}
void CEx23dView::OnUpdateClockoleLoad(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_clock.m_lpDispatch == NULL);
}
void CEx23dView::OnClockoleRefreshtime()
{
COleDateTime now = COleDateTime::GetCurrentTime();
m_clock.SetTime(now);
m_clock.RefreshWin();
}
void CEx23dView::OnUpdateClockoleRefreshtime(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_clock.m_lpDispatch != NULL);
}
void CEx23dView::OnClockoleUnload()
{
m_clock.ReleaseDispatch();
}
void CEx23dView::OnUpdateClockoleUnload(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_clock.m_lpDispatch != NULL);
}

Controlling Excel

The Ex23d program contains code that loads Excel, creates a workbook, and reads from and writes to cells from the active worksheet. Controlling Excel is exactly like controlling an MFC Automation component, but you need to know about a few Excel peculiarities.

If you study Excel VBA, you'll notice that you can use more than 100 "objects" in your programs. All of these objects are accessible through Automation, but if you write an MFC Automation client program, you'll need to know about the objects' properties and methods. Ideally, you want a C++ class for each object, with member functions coded to the proper dispatch IDs.

Excel has its own type library that is registered in the Registry. The Add Class From Typelib Wizard can read the type library after looking it up in the Registry. The wizard can create C++ driver classes for individual Excel objects. It makes sense to select the objects you need and then combine the classes into single files, as shown in Figure 23-6.

Figure 23-6: The Add Class From Typelib Wizard can create C++?? classes for the Excel objects listed in Excel's type library.

You might need to edit the generated code to suit your needs. Let's look at an example. If you use the Add Class From Typelib Wizard to generate a driver class for the Worksheet object, you get a get_Range member function, as shown here:

    LPDISPATCH get_Range(VARIANT Cell1, VARIANT Cell2)
{
LPDISPATCH result;
static BYTE parms[] = VTS_VARIANT VTS_VARIANT ;
InvokeHelper(0xc5, DISPATCH_PROPERTYGET, VT_DISPATCH, 
(void*)&result, parms, &Cell1, &Cell2);
return result;
}

You know (from the Excel VBA documentation) that you can call the method with either a single cell (one parameter) or a rectangular area specified by two cells (two parameters). Remember that you can omit optional parameters in a call to InvokeHelper. Now it makes sense to add a second overloaded get_Range function with a single cell parameter, like this:

LPDISPATCH get_Range( VARIANT Cell1) // added
{
LPDISPATCH result;
static BYTE parms[] = VTS_VARIANT;
InvokeHelper(0xc5, DISPATCH_PROPERTYGET, VT_DISPATCH,
(void*)&result, parms, &Cell1);
return result;
}

How do you know which functions to fix up? They're the functions you decide to use in your program. You'll have to read the Excel VBA reference manual to figure out the required parameters and return values. Perhaps someday soon someone will write a set of C++ Excel controller classes.

The Ex23d program uses the Excel objects and contains the corresponding classes shown in the following table. The code for these objects is contained in the files

CApplication.h ,

CRange.h ,

CWorksheet.h ,

CWorksheets.h , and

CWorkbooks.h .

The following view member function, OnExceloleLoad, handles the Excel Comp Load menu command. This function must work if the user already has Excel running on the desktop. The COM GetActiveObject function tries to return an IUnknown pointer for Excel. GetActiveObject requires a class ID, so we must first call CLSIDFromProgID. If GetActiveObject is successful, we call QueryInterface to get an IDispatch pointer and we attach it to the view's m_app controller object of class CApplication. If GetActiveObject is unsuccessful, we call COleDispatchDriver::CreateDispatch, as we did for the other components.

void CEx23dView::OnExceloleLoad()
{   // if Excel is already running, attach to it, otherwise start it
LPDISPATCH pDisp;
LPUNKNOWN pUnk;
CLSID clsid;
TRACE("Entering CEx23dView::OnExcelLoad\n");
BeginWaitCursor();
// Use Excel.Application.9 for Office 2000
// Use Excel.Application.10 for Office XP
::CLSIDFromProgID(L"Excel.Application.10", &clsid); // from registry
if(::GetActiveObject(clsid, NULL, &pUnk) == S_OK) {
VERIFY(pUnk->QueryInterface(IID_IDispatch,
(void**) &pDisp) == S_OK);
m_app.AttachDispatch(pDisp);
pUnk->Release();
TRACE(" attach complete\n");
} 
else {
if(!m_app.CreateDispatch("Excel.Application.10")) {
AfxMessageBox("Microsoft Excel program not found");
}
TRACE(" create complete\n");
}
EndWaitCursor();
}

OnExceloleExecute is the command handler for the Execute command on the Excel Comp menu. Its first task is to find the Excel main window and bring it to the top. We must write some Windows code here because a method for this purpose couldn't be found. We must also create a workbook if no workbook is currently open.

We have to watch our method return values closely. The Workbooks Add method, for example, returns an IDispatch pointer for a Workbook object and, of course, increments the reference count. If we generated a class for Workbook, we could call COleDispatchDriver::AttachDispatch so that Release would be called when the Workbook object was destroyed. We don't need a Workbook class, so we'll simply release the pointer at the end of the function. If we don't properly clean up our pointers, we might get memory-leak messages from the Debug version of MFC.

The rest of the OnExceloleExecute function accesses the cells in the worksheet. It's easy to get and set numbers, dates, strings, and formulas. The C++ code is similar to the VBA code you would write to do the same job:

void CEx23dView::OnExceloleExecute()
{
LPDISPATCH pRange, pWorkbooks;    
CWnd* pWnd = CWnd::FindWindow("XLMAIN", NULL);
if (pWnd != NULL) {
TRACE("Excel window found\n");
pWnd->ShowWindow(SW_SHOWNORMAL);
pWnd->UpdateWindow();
pWnd->BringWindowToTop();
}
m_app.put_SheetsInNewWorkbook(1);
VERIFY(pWorkbooks = m_app.get_Workbooks());
m_workbooks.AttachDispatch(pWorkbooks);
LPDISPATCH pWorkbook = NULL;
if (m_workbooks.get_Count() == 0) {
// Add returns a Workbook pointer, but we
//  don't have a Workbook class
pWorkbook = m_workbooks.Add(COleVariant((short) 0)); // Save the 
// pointer for later release
}
LPDISPATCH pWorksheets = m_app.get_Worksheets();
ASSERT(pWorksheets != NULL);
m_worksheets.AttachDispatch(pWorksheets);
LPDISPATCH pWorksheet = m_worksheets.get_Item(COleVariant((short) 1));
m_worksheet.AttachDispatch(pWorksheet);
m_worksheet.Select(COleVariant((short) 0));
VERIFY(pRange = m_worksheet.get_Range(COleVariant("A1"), 
COleVariant("A1")));
m_range[0].AttachDispatch(pRange);
VERIFY(pRange = m_worksheet.get_Range(COleVariant("A2"), 
COleVariant("A2")));
m_range[1].AttachDispatch(pRange);
VERIFY(pRange = m_worksheet.get_Range(COleVariant("A3"), 
COleVariant("A3")));
m_range[2].AttachDispatch(pRange);
VERIFY(pRange = m_worksheet.get_Range(COleVariant("A3"), 
COleVariant("C5")));
m_range[3].AttachDispatch(pRange);
VERIFY(pRange = m_worksheet.get_Range(COleVariant("A6"), 
COleVariant("A6")));
m_range[4].AttachDispatch(pRange);
m_range[4].put_Value(COleVariant(COleDateTime(2002, 4, 24, 
15, 47, 8)));
// retrieve the stored date and print it as a string
COleVariant vaTimeDate = m_range[4].get_Value();
TRACE("returned date type = %d\n", vaTimeDate.vt);
COleVariant vaTemp;
vaTemp.ChangeType(VT_BSTR, &vaTimeDate);
CString str(vaTemp.bstrVal);
TRACE("date = %s\n", (const char*) str);
m_range[0].put_Value(COleVariant("test string"));
COleVariant vaResult0 = m_range[0].get_Value();
if (vaResult0.vt == VT_BSTR) {
CString str(vaResult0.bstrVal);
TRACE("vaResult0 = %s\n", (const char*) str);
}
m_range[1].put_Value(COleVariant(3.14159));
COleVariant vaResult1 = m_range[1].get_Value();
if (vaResult1.vt == VT_R8) {
TRACE("vaResult1 = %f\n", vaResult1.dblVal);
}
m_range[2].put_Formula(COleVariant("=$A2*2.0"));
COleVariant vaResult2 = m_range[2].get_Value();
if (vaResult2.vt == VT_R8) {
TRACE("vaResult2 = %f\n", vaResult2.dblVal);
}
COleVariant vaResult2a = m_range[2].get_Formula();
if (vaResult2a.vt == VT_BSTR) {
CString str(vaResult2a.bstrVal);
TRACE("vaResult2a = %s\n", (const char*) str);
}   
m_range[3].FillRight();
m_range[3].FillDown();   
// cleanup  
if (pWorkbook != NULL) {
pWorkbook->Release();
}
}

The Ex23e Example: An Automation Client

This program uses the #import directive to generate smart pointers. It behaves just like Ex23d except that it doesn't run Excel. The #import statements are in the

StdAfx.h file to minimize the number of times the compiler has to generate the driver classes. Here is the added code:

#include <afxdisp.h>
#import "..\Ex23a\Debug\Ex23a.tlb" rename_namespace("BankDriv") 
using namespace BankDriv;
#import "..\Ex23b\Debug\Ex23b.tlb" rename_namespace("Ex23bDriv") 
using namespace Ex23bDriv;
#import "..\Ex23c\Debug\Ex23c.tlb" rename_namespace("ClockDriv")
using namespace ClockDriv;

If you have ActiveX controls turned on when you generate the code, the MFC Application Wizard will insert a call to AfxOleInit in your application class InitInstance member function. (Otherwise, you must add it by hand.)

The view class header contains embedded smart pointers, as shown here:

IEx23bAutoPtr m_auto;
IBankPtr m_bank;
IEx23cPtr m_clock;
IAlarmPtr m_alarm;

Here's the code for the view class menu command handlers:

void CEx23eView::OnBankoleLoad()
{
if(m_bank.CreateInstance(__uuidof(Bank)) != S_OK) {
AfxMessageBox("Bank component not found");
return;
}
}
void CEx23eView::OnUpdateBankoleLoad(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_bank.GetInterfacePtr() == NULL);
}
void CEx23eView::OnBankoleTest()
{
try {
m_bank->Deposit(20.0);
m_bank->Withdrawal(15.0);
TRACE("new balance = %f\n", m_bank->GetBalance());
} catch(_com_error& e) {
AfxMessageBox(e.ErrorMessage());
}
}
void CEx23eView::OnUpdateBankoleTest(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_bank.GetInterfacePtr() != NULL);
}
void CEx23eView::OnBankoleUnload()
{
m_bank.Release();
}
void CEx23eView::OnUpdateBankoleUnload(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_bank.GetInterfacePtr() != NULL);
}
void CEx23eView::OnClockoleCreatealarm()
{
CAlarmDlg dlg;
try {
if (dlg.DoModal() == IDOK) {
COleDateTime dt(2001, 12, 23, dlg.m_nHours, 
dlg.m_nMinutes, dlg.m_nSeconds);
LPDISPATCH pAlarm = m_clock->CreateAlarm(dt);
m_alarm.Attach((IAlarm*) pAlarm);  // releases prior object!
m_clock->RefreshWin();
}
} catch(_com_error& e) {
AfxMessageBox(e.ErrorMessage());
}
}
void CEx23eView::OnUpdateClockoleCreatealarm(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_clock.GetInterfacePtr() != NULL);
}
void CEx23eView::OnClockoleLoad()
{
if(m_clock.CreateInstance(__uuidof(CEx23cDoc)) != S_OK) {
AfxMessageBox("Clock component not found");
return;
}
try {
m_clock->PutFigure(0, COleVariant("XII"));
m_clock->PutFigure(1, COleVariant("III"));
m_clock->PutFigure(2, COleVariant("VI"));
m_clock->PutFigure(3, COleVariant("IX"));
OnClockoleRefreshtime();
m_clock->ShowWin();
} catch(_com_error& e) {
AfxMessageBox(e.ErrorMessage());
}
}
void CEx23eView::OnUpdateClockoleLoad(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_clock.GetInterfacePtr() == NULL);
}
void CEx23eView::OnClockoleRefreshtime()
{
COleDateTime now = COleDateTime::GetCurrentTime();
try {
m_clock->PutTime(now);
m_clock->RefreshWin();
} catch(_com_error& e) {
AfxMessageBox(e.ErrorMessage());
}
}
void CEx23eView::OnUpdateClockoleRefreshtime(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_clock.GetInterfacePtr() != NULL);
}
void CEx23eView::OnClockoleUnload()
{
m_clock.Release();
}
void CEx23eView::OnUpdateClockoleUnload(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_clock.GetInterfacePtr() != NULL);
}
void CEx23eView::OnDlloleGetdata()
{
try {
m_auto->DisplayDialog();
COleVariant vaData = m_auto->GetTextData();
ASSERT(vaData.vt == VT_BSTR);
CString strTextData(vaData.bstrVal);
long lData = m_auto->GetLongData();
TRACE("CEx23dView::OnDlloleGetdata—long = %ld, text = %s\n",
lData, strTextData);
} catch(_com_error& e) {
AfxMessageBox(e.ErrorMessage());
}
}
void CEx23eView::OnUpdateDlloleGetdata(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_auto.GetInterfacePtr() != NULL);
}
void CEx23eView::OnDlloleLoad()
{
if(m_auto.CreateInstance(__uuidof(Ex23bAuto)) != S_OK) {
AfxMessageBox("Ex23bAuto component not found");
return;
}
IEx23bAuto* pEx23bAuto = 0;
m_auto.QueryInterface(__uuidof(IEx23bAuto), (void**)&pEx23bAuto);
if(pEx23bAuto) {
pEx23bAuto->PutLongData(42);
pEx23bAuto->Release();
}
}
void CEx23eView::OnUpdateDlloleLoad(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_auto.GetInterfacePtr() == NULL);
}
void CEx23eView::OnDlloleUnload()
{
m_auto.Release();
}
void CEx23eView::OnUpdateDlloleUnload(CCmdUI *pCmdUI)
{
pCmdUI->Enable(m_auto.GetInterfacePtr() != NULL);
}

Note the use of the try/catch blocks in the functions that manipulate the components. These blocks are particularly necessary for processing errors that occur when a component program stops running. In the previous example, Ex23d, the MFC COleDispatchDriver class took care of this detail.