ActiveX Documents

ActiveX Documents

ActiveX documents are COM software components that present data and information to the user. ActiveX documents allow the user to view data in a variety of ways, perhaps as a graph, a spreadsheet, or text, depending on the purpose of the application. An ActiveX document cannot work alone, but always requires an environment in which to work. The environment is called an ActiveX container. Together, through an agreed-upon set of rules, the ActiveX container and ActiveX document work as one, and give the user the appearance of a single, homogeneous application.

If you look at an ActiveX document running inside an ActiveX container, you can visually identify each component. The ActiveX document occupies the client area of the container and negotiates with the container for menu and toolbar space. The ActiveX container is the frame that surrounds the client area. It shares its menu space and toolbar space with the document. Together, they appear as a single application—but in fact, they are separate pieces of software that work together cooperatively. The only reason they work together is because each follows a well-documented set of rules or COM interfaces. COM is the foundation of all of the OLE and ActiveX technologies. This chapter requires at least an architectural understanding of COM and will look at some of the COM interfaces involved in writing an ActiveX document, but certainly not all of the COM interfaces available. It is well worth your time to review COM and understand it. This chapter will help clarify and solidify your understanding of how ActiveX documents work.

In addition to exploring the COM interfaces required to create an ActiveX document, this chapter examines what has changed between OLE compound documents and ActiveX documents, what MFC classes have been added, and how the Active Template Library can be used to build an ActiveX document. In passing, this chapter mentions ActiveX containers. For more information about ActiveX containers, refer to Chapter 13, 'ActiveX Containers.'

Just What Is an ActiveX Document?

You might have heard quite a bit of commotion about ActiveX. Some say that ActiveX is nothing more than another name for OLE. Some say that ActiveX is the name for a new set of Internet technologies. The truth lies in a combination of the two. ActiveX is really an evolution of the Microsoft OLE strategy. It includes some new COM interfaces working together with existing OLE COM interfaces. It also includes some new technologies, such as ActiveX server extensions, ActiveX Server Pages, and ActiveVRML.

ActiveX documents fall into the first category—an evolution of OLE interfaces to support the needs of the Internet. In particular, ActiveX documents are OLE embedded documents with the addition of four new COM interfaces: IOleDocument, IOleDocumentView, IOleCommandTarget, and IPrint. These new interfaces allow for a significant difference between OLE embedded documents and ActiveX documents: ActiveX documents occupy the entire client area of an ActiveX container, whereas OLE embedded documents occupy a small, well-defined area. This was added so that users browsing the Web with a tool such as the Internet Explorer could click a hyperlink on a Web page and link directly to a Microsoft Word document, Microsoft Excel spreadsheet, or another application. To the user, it appears as though the application data is just another Web page with perhaps more menu items and toolbars. This provides the user with a positive and rich Internet experience.

ActiveX documents first appeared with the release of Microsoft Office 95. Microsoft Office Binder is an ActiveX container, and Microsoft Word and the other Office applications are ActiveX documents. In fact, it is quite interesting to notice the following in the Visual C++ header DOCOBJ.H:

#define IMsoDocument IOleDocument
#define IMsoView IOleDocumentView

Clearly, the IOleDocument and IOleDocumentView interfaces began life as Microsoft Office (Mso) interfaces. It should also be noted that ActiveX documents were originally referred to as DocObjects. You will notice API calls and interfaces that reference this name—for example, the new MFC class CDocObjectServer.

Let's look a little more closely at the four new COM interfaces:

• IOleDocument is one of the new required interfaces. It allows the container to determine various attributes about the document, to enumerate the views that are supported, and to create specific views.
• IOleDocumentView is another required new interface. It is the interface that the container uses to communicate with the view. Each view must support this interface in addition to existing OLE interfaces such as IOleInPlaceObject and IOleInPlaceActiveObject.
• IOleCommandTarget is an optional interface. It allows the container to route commands, that it doesn't handle, to the document. The container also exposes this interface and allows the document to route commands to the container.
• IPrint is an optional interface. It allows the container to print the contents of the document and to specify to the document what to print and how to print it. This interface works in conjunction with IContinueCallback that the container exposes. IContinueCallback allows the document to inform the container on printing status and allows the container to cancel the printing that is in progress.

What Is New in MFC?

There are two new MFC classes that encapsulate the new ActiveX document interfaces. They are CDocObjectServer and CDocObjectServerItem. CDocObjectServer supports the IOleDocument, IOleDocumentView, IOleCommandTarget, and IPrint interfaces. It is similar to what COleDocument does and replaces this class when you want to support ActiveX documents. CDocObjectServerItem supports OLE server verbs required for ActiveX documents. It derives from COleServerItem and overrides OnHide, OnOpen, and OnShow to implement ActiveX document support. It replaces COleServerItem when you want to support ActiveX documents.

Some Details about ActiveX Documents

ActiveX documents are the next step in the OLE evolution. They are built upon the foundation of OLE linked and embedded servers. In fact, an ActiveX document can choose to behave like an OLE linked or embedded document if the implementer chooses. Microsoft Word is a good example of this behavior. If you start Microsoft Excel, choose Insert Object, and insert Word into the spreadsheet, it will behave like an embedded document server, as shown in Figure 12.1.

FIGURE 12.1. Microsoft Word as an embedded document inside Microsoft Excel

If you start Microsoft Binder and add a Word document to the Binder container, it will behave like an ActiveX document. To determine whether a container supports the ActiveX document specification, it can be queried for support of the IOleDocumentSite interface. If the container supports this interface, the Document server can behave like an ActiveX document; otherwise, it should behave like an OLE linked or embedded document.

Because ActiveX documents have an OLE heritage, this chapter will spend some time discussing what it means to be an OLE linked or embedded Document server. OLE Document servers can be thought about in two ways: as in-process servers or local servers and as mini-servers or full servers. These are two separate issues to think about and can be combined as follows: An in-process server can be a mini-server (usually) or a full server (with some care). A local server can be a mini-server (not very often) or a full server (usually). Each of these issues is discussed below.

An in-process server is essentially a DLL. It means that the OLE Document server runs in the same address space as the container. Calls to the various OLE COM interfaces are no different than any other function calls within the container application. There is no additional overhead when you call the OLE Document server. For this reason, in-process servers are the most efficient and perform the best.

A local server is essentially an EXE. In this case, the OLE Document server runs in another address space. Calls to the var 232b18c ious OLE COM interfaces require special handling, called marshalling. Marshalling is the name for taking all the parameters to an OLE call, flattening them out, sending them over the process boundary, reassembling them on the other side, and calling the OLE interface in the servers address space. As you might imagine, this can be a rather tricky exercise. If you are passing a LONG as a parameter, it is fairly simple to move the data to another process. However, if you are moving a FOOBAR* to another address space, how do you move the data successfully so that the OLE server in another address space can reference it? Fortunately, most of this is handled automatically by OLE. OLE uses the IDL definitions to figure out how to marshall arguments—and, in fact, creates the necessary code to do all the work. The downside to this is that it is more expensive to make OLE calls using this technique as a result of all the marshalling that takes place.

A mini-server is an OLE Document server that only supports embedding. It can not be run stand-alone, and depends on the container for its user interface and storage capabilities. A mini-server is typically implemented as an in-process server. Although there is no reason to create a mini-server as an EXE, because it is not meant to run stand-alone, it is certainly possible to do so.

A full server is an OLE Document server that supports linking and embedding, and can be run as a stand-alone application. A full server is typically implemented as a local server. It is possible to write a full server as a DLL, but this would require another shell to load the DLL in stand-alone mode.

ActiveX documents are typically full servers. It is recommended that they run as stand-alone applications as well as ActiveX Document servers. If you create a new MFC OLE application, you will notice that on the page OLE support is specified you can add ActiveX document support only if the application is a full server, as shown in Figure 12.2. It is possible to write an ActiveX Document server as an in-process server.

FIGURE 12.2. MFC AppWizard dialog for creating an ActiveX document

OLE Document servers support linking, embedding, and in-place activation. Not all servers have to support these features. ActiveX documents are both embedded and always in-place active. They do not support linking; so this chapter won't spend any time discussing OLE linking issues.

An embedded OLE document lives within a part of a container and often exists with native container data, as well as other embedded documents. It can be activated by double-clicking or selecting Open from a context menu. OLE 1 specified that when an embedded document was opened that the native application would start and the user could edit the document using the native tool. Figure 12.3 illustrates an embedded document opened in its own native application.

OLE 2 specified that it was also possible to open the embedded document right within the context of the container. This is called in-place activation. ActiveX documents are always in-place active. In addition, they are the only embedded document in the container, and they occupy the entire client area.

OLE and ActiveX Document servers also have to support menu merging. When an OLE document is in-place active, it is given the opportunity to merge any menus that it has with the container's menu. This merging of menus is well-defined. OLE containers own and manage the File, Container, and Window menus. OLE documents own and manage the Edit, Object, and Help menus. ActiveX documents must do some additional Help menu merging.

FIGURE 12.3. Microsoft Word opened from Excel as a separate application

Drag-and-drop is optionally supported by OLE Document servers. OLE drag-and-drop works through the use of the IDataObject, IDropSource, and IDropTarget. IDropSource and IDropTarget are used to track mouse movements and show appropriate user feedback. Ultimately, the target of a drop operation obtains the IDataObject pointer from the IDropTarget interface, and using Uniform Data Transfer can obtain and manipulate the data through the IDataObject methods. The OLE Clipboard is also manipulated through the IDataObject methods.

OLE provides a means by which data from an OLE Document server can be saved with data from the container and other OLE Document servers into a single file. This technology is called structured storage. Through the use of the IPersistStorage, IStorage, and IStream interfaces, servers can store their data into a section of a single file. Structured storage makes a single file behave as if it were a file system, complete with hierarchical directories.

New to ActiveX documents is the concept of programmatic printing. With the OLE document architecture, it was up to the container to print out its own data. A container can contain several embedded documents, none of which knows anything about the environment in which it is displayed—much less about other embedded documents that are also in the same container environment. So, it would be impossible for an embedded document to control any aspect of printing. Only the container knows enough to control the printing. ActiveX documents change this. Because the document occupies the entire client area, it knows about all the data and can have full control over how the data is printed. ActiveX documents and containers do this through the use of the new IPrint and IContinueCallback interfaces.

The COM Interfaces

ActiveX documents, like their predecessor OLE documents, are built on the foundation of COM. Through a set of well-defined interfaces, it is possible to build an ActiveX document that can operate within any ActiveX container, without knowing anything more about the container than that it supports a set of COM interfaces. This architecture allows for a great deal of flexibility and enables the user to combine these ActiveX document components in ways perhaps not envisioned by the original programmers.

This section discusses 10 COM interfaces that make up the ActiveX document specification. Six of these interfaces are part of the original OLE document specification. Four of them are new to ActiveX. Two of the new ActiveX COM interfaces are optional: IPrint and IOleCommandTarget.

IOleObject

IOleObject is a COM interface with the largest number of methods. It provides the main interface for a container to communicate with an embedded object and is required if an object wants to support embedding. Table 12.1 describes the IOleObject interfaces.

Table 12.1. IOleObject interfaces

IDataObject

IDataObject is the means by which data is transferred between OLE objects. This technology is called Uniform Data Transfer. With IDataObject, data can be transferred using a particular format over a specific storage medium. It is also possible to advise others of changed data. Table 12.2 describes the IDataObject interfaces.

Table 12.2. IDataObject interfaces

IPersistStorage

IPersistStorage provides a means for a container to pass a storage interface to an embedded object. The IPersistStorage interface makes use of structured storage and allows object data to be stored in its own area within the structured storage. Table 12.3 describes the IPersistStorage interfaces.

Table 12.3. IPersistStorage interfaces

IPersistFile

IPersistFile provides an interface that allows the object to store itself on the file system rather than in a structured storage object. Table 12.4 describes the IPersistFile interfaces.

Table 12.4. IPersistFile interfaces

IOleDocument

IOleDocument is one of the new COM interfaces that supports ActiveX documents. It allows the container to discover what kind of views are supported by the document and to obtain pointers to those view interfaces. Table 12.5 describes the IOleDocument interfaces.

Table 12.5. IOleDocument interfaces

IOleInPlaceObject

IOleInPlaceObject allows a container to activate and deactivate an in-place active object. It also allows the container the opportunity to set the viewable area of the embedded object. Table 12.6 describes the IOleInPlaceObject interfaces.

Table 12.6. IOleInPlaceObject interfaces

IOleInPlaceActiveObject

IOleInPlaceActiveObject provides a means for the embedded object to communicate with the container's frame and the container's document window. Table 12.7 describes the IOleInPlaceActiveObject interfaces.

Table 12.7. IOleInPlaceActiveObject interfaces

IOleDocumentView

IOleDocumentView is another new COM interface that supports ActiveX documents. It provides the means for a container to communicate with each of the active document views. Table 12.8 describes the IOleDocumentView interfaces.

Table 12.8. IOleDocumentView interfaces

IPrint

IPrint is another new (and optional) ActiveX document COM interface. It allows the container to communicate printing information to the document. Table 12.9 describes the IPrint interface.

Table 12.9. IPrint interfaces

IOleCommandTarget

IOleCommandTarget is another new (and optional) ActiveX document COM interface. It provides a way for the container to pass on commands that it doesn't handle to the document. The reverse is also true; it provides a way for the document to pass on commands to the container. Table 12.10 describes the IOleCommandTarget interfaces.

Table 12.10. IOleCommandTarget interfaces

The Active Template Library

The Active Template Library (ATL) is a recent addition to the Visual C++ product. It came about primarily as a result of the explosive growth of the Internet and the Microsoft ActiveX strategy. The Microsoft ActiveX strategy is to create dynamic Web pages through the use of various ActiveX controls. In order for these controls to make sense in today's 28.8Kbit Internet market, the controls have to be small and compact so that they can be downloaded from Web servers quickly. To build these controls with MFC is certainly possible, but MFC applications are characteristically large and require large support DLLs. Another alternative to MFC was needed that could create smaller controls, without the need for support DLLs. The Active Template Library is the alternative that Microsoft has provided.

ATL and MFC differ in their approaches. Both libraries rely on C++ capabilities, but that is where their similarities end. MFC is build upon the concept of a class hierarchy. Most of the MFC classes derive from other classes, which eventually derive from CObject. This allows classes to inherit a lot of behaviors from their ancestors. As an example, consider the CButton class. It implements a handful of new methods but inherits a tremendous amount of behavior from the CWnd class. CWnd, in turn, inherits from CCmdTarget, which, inherits from CObject. A strategy like this has a few interesting characteristics:

• The class hierarchy tends to get deep and therefore requires a lot of study to grasp.
• Application behavior is accomplished by inheriting from certain classes and overriding methods. This creates a white box effect and again requires a lot of study to understand how to integrate changes into any new derived classes.
• After the learning curve has been overcome, it is possible to quickly implement applications because so much behavior can be inherited.

ATL takes a different approach. It is based on the concept of a template. A template is a way of capturing an algorithm in the form of a pattern. For example, if you had a mathematical formula such as x + y + z that you wanted to implement for integers and for floating-point numbers, you could create two classes:

class HighTechInteger


class HighTechFloat

Notice how both implementations have identical algorithms for their Calculate methods. Given these classes, however, you could never use the HighTechInteger class to handle floating-point numbers. You must maintain two separate classes. This creates opportunities for bugs to be introduced if both classes are not kept in sync. The alternative is to create a template:

template <Type> class HighTech



HighTech<int> htInteger;
HighTech<float> htFloat;

Notice how this unifies the source code base and increases code reliability since the algorithm is only implemented once.

Another feature of C++ that ATL makes use of is multiple inheritance. C++ allows one class to inherit from several parent classes. Grady Booch, in his book Object Oriented Design with Applications, describes special, lightweight classes that are designed for multiple inheritance as mixin classes. C++ multiple inheritance can be used in many ways, but classes designed for the mixin approach are typically thin, focused, and easily reusable. Let's consider a mixin scenario:

class subtractMixin


class MyCoolClass : public CoolBaseClass

class MyFriendsClass : public CoolBaseClass

Suppose that the subtractMixin class was a useful, reusable algorithm that could be used in a variety of situations—it could be mixed in with many different classes. One way to implement

this kind of feature would be as a separate class that could be inherited from to obtain the desired behavior. This class would be considered a mixin class. Mixin classes do not necessarily provide usefulness by themselves, but are useful as additive behaviors. Now suppose you wanted your MyCoolClass to have the capability to subtract as well as add. You could define another method in the MyCoolClass class or just inherit the behavior from subtractMixin:

class MyCoolClass : public CoolBaseClass, public subtractMixin

In addition, you could add subtract behavior to MyFriendsClass or any other class by inheriting from subtractMixin. However, it is not very useful to create an instance of subtractMixin by itself. Classes such as subtractMixin are called mixin classes, and provide an interesting and useful alternative to deep-class hierarchies.

ATL makes use of both the template concept and the mixin concept. Because many of the COM interfaces are small and clean, they lend themselves to being used as mixin classes. The ATL strategy has these characteristics:

There is no large class hierarchy to learn, but there are a number of mixin classes to learn.

Application behavior is accomplished by inheriting from the required number of mixin classes. This approach tends to be more black box, although not necessarily.

It takes more effort to implement the application. Unlike MFC applications that inherit a great deal of behavior, ATL applications inherit only the necessities and must implement the rest manually.

ATL applications are smaller than MFC applications as a result of shallow class hierarchies.

ATL Classes Required for ActiveX Document Support

The following provides an overview of some of the ATL classes that you will see in the ACTIVEDOC sample program:

CComObjectRoot

CComObjectRoot is a typedef of CComObjectRootEx. All ATL classes must inherit from this class. This class provides support for all the IUnknown interfaces and maintains the COM object's reference counts. It also determines whether the object will support single or multiple threading.

CComCoClass

CComCoClass is used to obtain CLSID and error information, and determines the default class factory. All classes that must be visible externally should inherit from this class.

CComControl

CComControl provides a number of useful functions for implementing ActiveX controls.

IDispatchImpl

IDispatchImpl provides an implementation of IDispatch.

IProvideClassInfo2Impl

IProvideClassInfo2Impl provides type library information.

IPersistStreamInitImpl

IPersistStreamInitImpl provides a means of storing application data on a single storage stream.

IPersistStorageImpl

IPersistStorageImpl provides a means of asking the object to save and load itself from a storage object.

IQuickActivateImpl

IQuickActivateImpl provides a means for a container to ask for all the interfaces that an object supports all at once.

IOleControlImpl

IOleControlImpl provides an implementation of IOleControl.

IOleObjectImpl

IOleObjectImpl provides an implementation of IOleObject.

IOleInPlaceActiveObjectImpl

IOleInPlaceActiveObjectImpl provides an implementation of IOleInPlaceActiveObject.

IViewObjectExImpl

IViewObjectExImpl provides implementations of IViewObject, IViewObject2, and IViewObjectEx.

IOleInPlaceObjectWindowlessImpl

IOleInPlaceObjectWindowlessImpl provides an implementation of IOleInPlaceObject and IOleInPlaceObjectWindowless.

IDataObjectImpl

IDataObjectImpl provides an implementation of IDataObject.

ISupportErrorInfo

ISupportErrorInfo defines a means by which the application can return error information to the container.

The ACTIVEDOC Program

Let's look at some code to understand how ATL can be used to create an ActiveX document. We will be looking at a sample program called ACTIVEDOC found on the Microsoft Visual C++ 5.0 CD. It can be located in the DEVSTUDIOVcSamplesAtlACTIVEDOC directory. We will focus in on specific areas of this sample code to see how an ATL application is built.

This example builds an in-process ActiveX document around the RichEdit control. The majority of the code is actually in the RichEdit control. The ACTIVEDOC program wraps an ActiveX Document layer around the control and provides a unique opportunity to focus on ATL issues, without being distracted by all the other issues that an application normally would have to worry about. In particular, we will look closely at the declaration of the CActiveDoc class and will notice how COM support is easily added through the mixin concept. We will also look at how support for the new IOleDocument and IOleDocumentView COM interfaces is added. When this example is built, it can be run inside Microsoft Binder or Microsoft Internet Explorer. Figure 12.4 illustrates the ACTIVEDOC program inside Microsoft Binder.

FIGURE 12.4. The ACTIVEDOC program inside Microsoft Binder

There are 19 files found in the ACTIVEDOC subdirectory. Table 12.11 briefly describes these files.

Table 12.11. Files found in the ACTIVEDOC directory

We will focus on two keys files in this project: activectl.h and oledocument.h. These files contain the majority of the code that we will be interested in. We will also review some other files as we encounter them.

activectl.h

This file contains the definition of the CActiveDoc class and most of the implementation code. CActiveDoc is the class that implements all the support for ActiveX documents. As we step through this header, we will discuss the important features of the CActiveDoc class.

The following code is from the beginning of activectl.h and shows the include files required by CActiveDoc. The first file, resource.h, is the standard header file that is generated by Visual C++ when dialogs or other resources are added to the project. It contains all the defines necessary for these resources. OleDocument.h is the header file that defines and implements two new classes: IOleDocumentImpl and IOleDocumentViewImpl. We will look more closely at this file later. Menu.h and toolbar.h provide definitions for CMenu and CToolbar. RichEdit.h is the standard header file that describes the RichEdit control.

// ActiveCtl.h : Declaration of the CActiveDoc class

#include 'resource.h' // main symbols
#include 'OleDocument.h'
#include 'Menu.h'
#include 'ToolBar.h'
#include <RichEdit.h>

Next is the definition of the CActiveDoc class interface. Let's look at the inheritance that the class uses. Notice, as mentioned above, that CActiveDoc is defined through multiple inheritance, or mixins. If you wanted to add or remove functionality from CActiveDoc, you would add or remove a class from which it inherits. Most of the classes that CActiveDoc inherits from are in fact OLE interfaces. Other required classes that CActiveDoc inherits from are CComObjectRoot and CComCoClass. Both of these classes are required. Finally, CActiveDoc inherits from two new classes: IOleDocumentImpl and IOleDocumentViewImpl. These new classes are not part of the ATL library but are defined in the oledocument.h file.

For your information, CLSID_CActiveDoc is the unique OLE identifier for CActiveDoc. It is defined in activedoc.h. IID_IActiveDoc is the unique COM interface identifier for ActiveDoc. It is also defined in activedoc.h. Most of the implementation templates, those that have the Impl at the end of their name, use CActiveDoc as the parameter to the template. This provides a connection between the template classes and the ActiveX document class that you are building. This declaration of CActiveDoc indicates that CActiveDoc supports all the COM interfaces listed in the inheritance list.

// CActiveDoc
class CActiveDoc :
public CComObjectRoot,
public CComCoClass<CActiveDoc, &CLSID_CActiveDoc>,
public CComControl<CActiveDoc>,
public IDispatchImpl<IActiveDoc, &IID_IActiveDoc, &LIBID_ACTIVEDOCLib>,
public IProvideClassInfo2Impl<&CLSID_CActiveDoc, NULL, &LIBID_ACTIVEDOCLib>,
public IPersistStreamInitImpl<CActiveDoc>,
public IPersistStorageImpl<CActiveDoc>,
public IQuickActivateImpl<CActiveDoc>,
public IOleControlImpl<CActiveDoc>,
public IOleObjectImpl<CActiveDoc>,
public IOleInPlaceActiveObjectImpl<CActiveDoc>,
public IViewObjectExImpl<CActiveDoc>,
public IOleInPlaceObjectWindowlessImpl<CActiveDoc>,
public IDataObjectImpl<CActiveDoc>,
public ISupportErrorInfo,
public IOleDocumentImpl<CActiveDoc>,
public IOleDocumentViewImpl<CActiveDoc>,
public CMenu<CActiveDoc>,
public CToolbar<CActiveDoc>

Take a look at the next section of the CActiveDoc declaration and implementation:

The class declaration begins with the constructor CActiveDoc(), a part of which is an initialization of m_wndRTF. If you look at the very end of the class declaration, you will notice that m_wndRTF is declared as CContainedWindow. CContainedWindow allows you to either superclass or subclass an existing control. In addition, it connects the existing control to the class that contains it. In our example, CActiveDoc is being declared as a superclass of a RichEdit control. m_wndRTF will provide the connection between the RichEdit control and CActiveDoc. All the message handling for the control will be routed through the CActiveDoc class message maps.

In the next section we encounter the DECLARE_REGISTRY_RESOURCEID macro:

DECLARE_REGISTRY_RESOURCEID(IDR_ActiveDoc)

This macro is defined as follows inatlcom.h:

#define DECLARE_REGISTRY_RESOURCEID(x)
static HRESULT WINAPI UpdateRegistry(BOOL bRegister)

This macro declares a static method called UpdateRegistry. The purpose of this method is to either add or remove the required Registry entries for the ActiveX document. The ATL Object Wizard automatically generates an RGS, or Registry script file. The Registry script file is a specially encoded file that describes, in Backus-Nauer form, the required Registry entries to operate the ActiveX document. The RGS file for this project is as follows:

HKCR

}
ActiveDoc.ActiveDoc = s `ActiveDoc Class'

NoRemove CLSID
= s `ActiveDoc Class'

ForceRemove `Control'
`DocObject' = s `8'
ForceRemove `Programmable'
ForceRemove `Insertable'
ForceRemove `ToolboxBitmap32' = s `%MODULE%, 1'
`MiscStatus' = s `0'

`TypeLib' = s `'
`Version' = s `1.0'
}
}

I won't discuss the syntax of the RGS file in this chapter, but you might recognize some familiar text that is part of this file. For example, the name of the ActiveX document is ActiveDoc Class. You can see what its CLSID is. Notice the familiar Registry keywords such as ProgID, InprocServer32, and Insertable. Fortunately, you don't have to write any code to read this file. There is a special routine that is included as part of the ATL library that knows how to read this file and make the appropriate Registry entries. This special routine will be invoked when UpdateRegistry is eventually called.

Following the DECLARE_REGISTRY_RESOURCEID macro are a number of macros enclosed by BEGIN_COM_MAP and END_COM_MAP.

BEGIN_COM_MAP(CActiveDoc)

COM_INTERFACE_ENTRY(IActiveDoc)
COM_INTERFACE_ENTRY(IDispatch)
COM_INTERFACE_ENTRY_IMPL(IViewObjectEx)
COM_INTERFACE_ENTRY_IMPL_IID(IID_IViewObject2, IViewObjectEx)
COM_INTERFACE_ENTRY_IMPL_IID(IID_IViewObject, IViewObjectEx)
COM_INTERFACE_ENTRY_IMPL(IOleInPlaceObjectWindowless)
COM_INTERFACE_ENTRY_IMPL_IID(IID_IOleInPlaceObject, IOleInPlaceObjectWindowless)
COM_INTERFACE_ENTRY_IMPL_IID(IID_IOleWindow, IOleInPlaceObjectWindowless)
COM_INTERFACE_ENTRY_IMPL(IOleInPlaceActiveObject)
COM_INTERFACE_ENTRY_IMPL(IOleControl)
COM_INTERFACE_ENTRY_IMPL(IOleObject)
COM_INTERFACE_ENTRY_IMPL(IQuickActivate)
COM_INTERFACE_ENTRY_IMPL(IPersistStorage)
COM_INTERFACE_ENTRY_IMPL(IPersistStreamInit)
COM_INTERFACE_ENTRY_IMPL(IDataObject)
COM_INTERFACE_ENTRY_IMPL(IOleDocument)
COM_INTERFACE_ENTRY_IMPL(IOleDocumentView)
COM_INTERFACE_ENTRY(IProvideClassInfo)
COM_INTERFACE_ENTRY(IProvideClassInfo2)
COM_INTERFACE_ENTRY(ISupportErrorInfo)
END_COM_MAP()

These macros create a COM interface map that is similar to the message maps used in MFC. They create a way for the QueryInterface call to determine whether this COM object supports a specific COM interface, and they provide a mapping to the classes that implement the specified interface. The macros used in the COM interface map can be found in atlcom.h and are defined as follows:

#define COM_INTERFACE_ENTRY(x)
,

#define COM_INTERFACE_ENTRY_IID(iid, x)


#define COM_INTERFACE_ENTRY_IMPL(x)
COM_INTERFACE_ENTRY_IID(IID_##x, x##Impl<_ComMapClass>)

#define COM_INTERFACE_ENTRY_IMPL_IID(iid, x)
COM_INTERFACE_ENTRY_IID(iid, x##Impl<_ComMapClass>)

These macros provide two ways of mapping an interface ID (IID) to a class method. COM_INTERFACE_ENTRY generates the IID for you by concatenating the string IID_ with the parameter that you supply. COM_INTERFACE_ENTRY_IID allows you to specify the IID yourself. COM_INTERFACE_ENTRY_IMPL and COM_INTERFACE_ENTRY_IMPL_IID are similar but map to templatized versions of interfaces.

The next section of activectl.h contains the macros BEGIN_PROPERTY_MAP and END_PROPERTY_MAP. These macros are used to define properties for ActiveX controls and will not be discussed at this time.

BEGIN_PROPERTY_MAP(CActiveDoc)
// PROP_ENTRY('Description', dispid, clsid)
END_PROPERTY_MAP()

Next is a section that begins with BEGIN_MSG_MAP and END_MSG_MAP:

BEGIN_MSG_MAP(CActiveDoc)
MESSAGE_HANDLER(WM_PAINT, OnPaint)
MESSAGE_HANDLER(WM_GETDLGCODE, OnGetDlgCode)
MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus)
MESSAGE_HANDLER(WM_KILLFOCUS, OnKillFocus)
MESSAGE_HANDLER(WM_CREATE, OnCreate)
MESSAGE_HANDLER(WM_DESTROY, OnDestroy)
MESSAGE_HANDLER(WM_ERASEBKGND, OnEraseBackgnd)
COMMAND_RANGE_HANDLER(ID_BLACK, ID_BLUE, OnColorChange)
COMMAND_ID_HANDLER(ID_HELP_ABOUT, OnHelpAbout)
NOTIFY_CODE_HANDLER(TTN_NEEDTEXT, OnToolbarNeedText)
ALT_MSG_MAP(1)
MESSAGE_HANDLER(WM_CHAR, OnChar)
END_MSG_MAP()
END_MSG_MAP()

These macros are very similar to the message maps that are found in MFC. They create a mapping between a Windows message and a method that supports the message.

Next are some macros that define the toolbar that is part of this ActiveX document:

BEGIN_TOOLBAR_MAP(CActiveDoc)
TOOLBAR_BUTTON(ID_BLACK)
TOOLBAR_BUTTON(ID_RED)
TOOLBAR_BUTTON(ID_GREEN)
TOOLBAR_BUTTON(ID_BLUE)
TOOLBAR_SEPARATOR()
TOOLBAR_BUTTON(ID_HELP_ABOUT)
END_TOOLBAR_MAP()

As official-looking as these macros are, they are not part of ATL. The definition of these macros can be found in toolbar.h, as follows:

#define BEGIN_TOOLBAR_MAP(x) public:
const static int* _GetToolbarEntries(int& nButtons) ; nButtons = sizeof(_entries)/sizeof(int); return _entries; }

These macros create an array of toolbar IDs and a method called GetToolbarEntries, which will return the number of buttons and a pointer to the entry array.

The rest of activectl.h deals with the implementation of specific COM methods. As you peruse this code, you will notice that each COM method uses the STDMETHOD macro. This macro is used to describe the standard calling conventions that all COM interfaces must follow. STDMETHOD is defined as follows where STDMETHODCALLTYPE is defined as _stdcall.

#define STDMETHOD(method) virtual HRESULT STDMETHODCALLTYPE method

The rest of activectl.h provides an inline implementation of the code. Only five inherited methods are overridden: IOleInPlaceActiveObjectImpl::OnDocWindowActive, IPersistStorageImpl::IsDirty, IPersistStreamInitImp::Save, IPersistStreamInitImp::Load, and IOleInPlaceObjectWindowlessImpl::SetObjectRects. I will not discuss the details of these methods. However, note that because only five methods have been overridden, the rest of the COM support was inherited as-is from the ATL base classes.

To summarize, there are a number of pieces of code in activectl.h that provide the framework for ActiveX document support. First, the CActiveDoc class inherits from a number of required COM interface classes. Second, the Registry must be configured with correct entries so that ActiveX containers will know how to load and run the ActiveX document. Third, the ActiveX document interfaces have to be exposed through the QueryInterface method. Much of this is done by using the various COM_INTERFACE macros to map an interface with an implementation of the interface. Again, many of these interfaces are inherited from base classes. Fourth, methods that require changing or enhancing have to be overridden.

oledocument.h

This file contains a templatized form of the definitions and implementations of the IOleDocument and IOleDocumentView COM interfaces. Support for these interfaces is not provided as part of the ATL library. You could use this header file in your own application to provide support for the IOleDocument and IOleDocumentView interfaces. However, the implementation of these interfaces supports only one view object. If your project requires more than one view, you will need to enhance these classes.

IOleDocumentImpl implements the IOleDocument methods CreateView, GetDocMiscStatus, and EnumViews.

#include <docobj.h>


// IOleDocumentImpl
template <class T>
class ATL_NO_VTABLE IOleDocumentImpl


// Return the view
*ppView = pView;

return S_OK;
}
STDMETHOD(GetDocMiscStatus)(DWORD *pdwStatus)

STDMETHOD(EnumViews)(IEnumOleDocumentViews** /*ppEnum*/, IOleDocumentView
**ppView)

Notice that the preceding implementation of EnumViews has only one pointer to a view interface: ppView. As a result, this implementation of IOleDocument supports only one instance of a view. It is certainly possible to support more than one—but to do this, you will have to extend these template classes.

Besides doing some error checking, CreateView does two basic things: It accepts an IOleInPlaceSite pointer if one is provided, and it returns a pointer to its only view. To obtain the view interface pointer, it calls its own InternalQueryInterface routine.

GetDocMiscStatus is called by the container to determine what kind of support is provided by the object. This implementation of IOleDocument returns DOCMISC_NOFILESUPPORT. This tells the container that this object does not support reading and writing to files. Other possible status values are shown in Table 12.12.

Table 12.12. DOCMISC status values

Because this object supports only one view, EnumViews returns a pointer to its IOleDocumentView interface.

IOleDocumentViewImpl implements the IOleDocumentView methods: SetInPlaceSite,
GetInPlaceSite, GetDocument, SetRect, GetRect, SetRectComplex, Show, UIActivate, Open,
CloseView, SaveViewState, ApplyViewState, and Clone.

SetRectComplex, Open, SaveViewState, ApplyViewState, and Clone are not implemented by this version of the IOleDocumentView interface. The rest of the methods are fairly straightforward, with the exception of ActiveXDocActive, which is a helper method of this class that does most of the work of activating the ActiveX document. The tasks that ActiveXDocActive performs are the standard sequence of events that any ActiveX document must follow in order to activate itself inside an ActiveX container. Let's look more closely at this method.

The first item this method takes care of is to make sure that the ActiveX document is in- place active:

if (!pT->m_bInPlaceActive)

pT->m_bInPlaceActive = TRUE;

Next, this method obtains the location of the in-place active window inside the container. It ensures that the ActiveX document window is visible, creating itself (if necessary), and remembers the rectangles by calling the SetObjectRects method.

if (pT->m_spInPlaceSite->GetWindow(&hwndParent) == S_OK)

else
pT->m_hWnd = pT->Create(hwndParent, rcPos);
}
pT->SetObjectRects(&rcPos, &rcClip);

After making itself visible, the method goes on to make itself UIActive by calling the IOleInPlaceSite's OnUIActivate() method. After that, it synchronizes the IOleInPlaceFrame and IOleInPlaceUIWindow interfaces by calling their SetActiveObject() and SetBorderSpace() methods.

CComPtr<IOleInPlaceActiveObject> spActiveObject;
QueryInterface(IID_IOleInPlaceActiveObject, (void**)&spActiveObject);

// Gone active by now, take care of UIACTIVATE
if (pT->DoesVerbUIActivate(iVerb))

if (spInPlaceFrame)
spInPlaceFrame->SetBorderSpace(NULL);
if (spInPlaceUIWindow)
spInPlaceUIWindow->SetBorderSpace(NULL);
}

Finally, the method merges its own menus with the container's menus and tells the container to position the ActiveX document so that it is viewable to the user by calling the ShowObject() method of the IOleClientSite interface.

// Merge the menus
pT->InPlaceMenuCreate(spInPlaceFrame);
pT->m_spClientSite->ShowObject();
return S_OK;

In summary, activectl.h and oledocument.h provide most of the support for ActiveX documents. The CActiveDoc class inherits most of its behavior, whereas oledocument.h was written specifically for the ACTIVEDOC sample from scratch and provides support for IOleDocument and IOleDocumentView. When you write your own ActiveX document using the ATL library, you will need to implement code that is very similar to the CActiveDoc class. You might also want to borrow and enhance the IOleDocument and IOleDocumentView support that is found in oledocument.h.

activedoc.htm

The final file I will discuss is activedoc.htm. This file deserves an honorary mention even though it is very straightforward. It is an HTML file that allows an ActiveX document to be viewed inside Internet Explorer. If you have Internet Explorer installed on your machine and you double-click this file, you will see the window shown in Figure 12.5.

FIGURE 12.5. The sample ACTIVEDOC program inside Internet Explorer

This HTML file demonstrates how you can implement a very lightweight ActiveX document object and include it in your Web pages. The key to activating the ActiveX document object is the OBJECT HTML keyword. Using the CLSID supplied as part of this keyword, Internet Explorer can look up the object in the Registry. Having found the object in the Registry, Internet Explorer can discover that the object supports the ActiveX document interface and interact with it as an ActiveX container.

<HTML>
<HEAD>
<TITLE>ATL 2.0 test page for object ActiveDoc</TITLE>
</HEAD>
<BODY>
<OBJECT ID='ActiveDoc' <
CLASSID='CLSID:93901785-436B-11D0-B965-000000000000'>
>
</OBJECT>
</BODY>
</HTML>

Summary

This chapter has begun to explore ActiveX documents. ActiveX documents owe much to their OLE document heritage. They share many of the same COM interfaces and add a few new ones of their own.

There are a number of ways to implement an ActiveX document. You could use native COM APIs and do most of the work yourself. You could use MFC. This, in fact, is the easiest tool to use. However, MFC applications tend to be large and for that reason are not suited to downloading over the Internet. Finally, you could use the recent ATL library as you saw in the Microsoft sample program ACTIVEDOC. ATL allows you to build smaller executables but does require a little more work on the part of the programmer.