Sample Code

In case you have not noticed, this book contains a companion CD as opposed to a disk, so there is a lot of sample code that we'll see discussed in the chapters ahead. The installation program on the CD will create a number of directories with the contents shown in Table 1-1. I suggest that you install these samples in a C:\INOLE directory if at all possible because the registry files assume this location. (See "Registry Files" later in this chapter.) For a description of the files in each of these directories, please refer to the CONTENTS.TXT file in the installation directory. Most of the samples compile to both 16-bit and 32-bit OLE except for those that rely on features available only with 32-bit OLE. CONTENTS.TXT points out those samples that are 32-bit specific. As 32-bit OLE is all Unicode, all 32-bit samples compile to Unicode as well.

Table 1-1.

Directories created by the installation procedure.

When citing specific samples, this book will point to one of the directories listed in Table 1-1 followed by the subdirectory containing the sample. For example, CHAP02\QUERY is a reference to the "Query" sample of Chapter 2; INC\BOOKGUID.H points to a header file in the shared INC directory.

Many samples in this book are simple demonstrations of the ideas behind a technology or an interface. There are two sample applications—Cosmo and Patron—that you'll find in a number of chapters, both of which are based on the CLASSLIB framework.12 These serve to illustrate how to add various OLE features to an existing application as well as a new application, and both evolve throughout the book. Cosmo, a little graphical editor shown in Figure 1-15 on the following page, starts in CHAP01\COSMO as a fully featured application that doesn't do anything with OLE. You draw a figure by simply clicking the mouse to add points, and you can change the colors and the line style used. As we progress through this book, we'll change and add features to use OLE as described in CONTENTS.TXT. In particular, this application gets a full OLE Automation treatment and also becomes a server for compound document content objects. In addition, we'll break the graphical part of Cosmo into a separate component, called Polyline, which also evolves through various chapters.

Figure 1-15.

The Cosmo application with several open Polyline figures.

Patron is a companion application that manages documents, in which each document has pages, as shown in Figure 1-16. Webster's defines patron as "one who uses the services of another establishment" or "the proprietor of an establishment (such as an inn)." As described in CONTENTS.TXT, Patron will evolve into a container for various types of objects—bitmaps, metafiles, compound document objects, and controls—that are the "tenants" that stay in the pages in the document. So this application really is running some sort of establishment and providing services to its customers. In CHAP01\PATRON, this application does next to nothing. All you can do is open new documents; add, remove, or navigate through pages; and format the document according to printer device information. You cannot place anything on a page, nor can you save a document. We'll add such features in later chapters, using Patron to illustrate building a new application with OLE technologies. I've left out some features initially because creating them without OLE would take a horrendous amount of code. Call it laziness if you want. I call it planning.

As Cosmo, Patron, and other samples evolve through the book, I've consistently marked the modifications made in each chapter with two comments: //CHAPTERxxMOD and //End CHAPTERxxMOD, where xx is the relevant chapter number. These delimiters will help you see what changes I had to make to header (H), source (CPP), and resource (RC) files in order to support the feature under discussion in that chapter. For example, if you want to

Figure 1-16.

The Patron application with several open documents.

see which variables I added to a class to support a specific feature, look in the H files, and you'll see the new ones between these comments. With these comments, you'll be able to see how a new feature fits into an overall application, especially because many OLE features make sense only in a larger application. But at the same time, you won't have to struggle to figure out which parts of the application have to do with that feature and which parts deal with other features.

I should also point out that many of the design techniques used in the sample code do not represent singular ways of accomplishing any particular goal. For example, the techniques I use to implement an object and its interfaces are not in any way part of OLE; they are simply my own techniques and do not represent Truth. "If it's Truth you're interested in," as Indiana Jones would remind us, "Dr. Tyree's philosophy class is right down the hall." What's important in OLE is that you provide the right vtable for an interface, and that's really the proverbial it.