InformIT: Visual C++ 6 Unleashed > Some Details About Active Documents

Table of Contents

Some Details About Active Documents

Active documents are the next step in OLE evolution; they are built on the foundation of OLE documents. In fact, an Active document can behave like an OLE 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, the Word document behaves like an embedded document server, as Figure 25.1 shows.

Figure 25.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 behaves like an Active document. To determine whether a container supports the Active document specification, you can query it for support of the IOleDocumentSite interface. If the container supports this interface, the document server can behave like an Active document; otherwise, it should behave like an OLE document.

Because Active documents have an OLE heritage, this chapter spends some time discussing what it means to be an OLE document server. You can think of OLE document servers in two ways: as in-process servers or local servers and as miniservers or full servers. An in-process server can be a miniserver (usually) or a full server (with some care). A local server can be a miniserver (not very often) or a full server (usually).

An in-process server is essentially a dynamic link library (DLL), which 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 very little additional overhead when you call the OLE document server. For this reason, in-process servers are the most efficient and perform better than local servers.

A local server is essentially an executable. In this case, the OLE document server runs in another address space. Calls to the various OLE COM interfaces require special handling, called marshaling. Marshaling is the term 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 server's 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. If you are moving a CMyObject* to another address space, though, 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 the COM remoting architecture. COM uses the Interface Definition Language (IDL) definitions to figure out how to marshal arguments—and, in fact, COM creates the necessary code to do all the work. The downside to this technique is that it is more expensive to make COM and OLE calls because of all the marshaling that takes place.

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

A full server is an OLE document server that supports linking and embedding and can run as a standalone application. A full server typically is 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 standalone mode.

Active document servers are typically full servers. It is recommended that they run as standalone applications as well as Active document servers. If you create a new MFC OLE application, you will notice that on the wizard page used to specify OLE support, you can add Active document support only if the application is a full server (see Figure 25.2). It is possible to write an Active document server as an in-process server.

Figure 25.2 The MFC AppWizard dialog box for creating an Active document.

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

An embedded OLE document resides within part of a container and often exists with native container data, as well as other embedded documents. You can activate an embedded OLE document by double-clicking it or by right-clicking it and choosing Open from the context menu. OLE 1.0 specifies that when you open an embedded document, the native application starts and you can edit the document using the native tool. Figure 25.3 shows an embedded document open in its native application.

Figure 25.3 Microsoft Word opened from Excel as a separate application.

OLE 2.0 (now simply known as OLE) specifies that you also can open an embedded document within the context of the container. This action is called in-place activation. An Active document is always in-place active. In addition, it is the only embedded document in the container, and it occupies the entire client area.

OLE and Active document servers also have to support menu merging. When an OLE document is in-place active, it has the opportunity to merge any menus it has with the container's menus. 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. Active documents must do some additional Help menu merging.

The drag-and-drop capability is supported optionally by OLE document servers. OLE drag-and-drop works through the use of IDataObject, IDropSource, and IDropTarget. IDropSource and IDropTarget 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, it obtains and manipulates the data through the IDataObject methods. The OLE Clipboard also is 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 in 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 Active documents is the concept of programmatic printing. With the OLE document architecture, it is 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. It therefore would be impossible for an embedded document to control any aspect of printing. Only the container knows enough to control the printing. Active 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. Active documents and containers do this by using the new IPrint and IContinueCallback interfaces.

The COM Interfaces | Next Section

Previous Section