Chapter 23

ActiveX Document Fundamentals

• What Is an ActiveX Document?
  • ActiveX Documents and ActiveX Controls
• ActiveX Document Programming
  • Should You Use a DLL or an EXE Server?
  • ActiveX Document Display
  • The Life and Times of an ActiveX Document
  • Versioning
  • Containers
  • Menus
  • Error Checking
• The UserDocument Object
  • Ambient and Extender Properties
  • Parent and Other Client Properties
  • Property Persistence
  • Tips and Tricks

From a programming perspective, ActiveX documents are almost identical to ActiveX controls. In fact, the greatest challenge you are likely to face is understanding exactly what ActiveX documents are and how they differ from controls.

So we'll begin this chapter with a discussion of the philosophy of ActiveX documents, focusing on the assumption that the most likely use for this type of component is on Internet and intranet Web sites. We'll conclude with a surprisingly short section discussing ActiveX document programming. Short, because you already know almost everything you need to know from our discussions relating to other types of components.

And what if you have skipped directly to this chapter because all you want to do is write ActiveX documents and you don't want to waste your time learning how to write ActiveX code components and controls first? Sorry, but you are about to become extremely confused, because I am definitely assuming that you have read the entire book before reaching this point.

What Is an ActiveX Document?

In order to really understand ActiveX documents, you need to go back to Chapter 2and recall our discussion on the idea of docu-centric programming. In this approach we distinguish between a document, such as a word document or video clip, and the application that can service (open, edit, display, save) the document. So when you talk about ActiveX documents, you are really talking about two different things: the document itself and the ActiveX DLL or EXE server that supports it.

When you create a new ActiveX document project, you are actually creating both of these elements: the server, and an empty document. A single server can support an unlimited number of documents, just as Microsoft Word can support any number of document files. The server for an ActiveX document can be an EXE or a DLL server. The document generally has the extension .VBD, though ActiveX documents can be stored within other files as well, using a mechanism called OLE structured storage.

This division between server and document may seem obvious, but I found that it is very easy to lose sight of when reading the Visual Basic documentation for ActiveX documents. Table 23.1 illustrates the similarities between Word documents and ActiveX documents.

When you compile or run a new ActiveX document server, Visual Basic creates an empty .VBD file that has no properties set. When you load an empty .VBD file, the UserDocument's InitProperties event will trigger. If you save the object, the object will write out its properties into the .VBD file during the UserDocument's WriteProperties event. From then on, when you open the .VBD file, a ReadProperties event will trigger to prompt the server to read the properties from the .VBD file. Sounds just like an ActiveX control, doesn't it?

ActiveX Documents and ActiveX Controls

Even though ActiveX documents and ActiveX controls are extremely similar when it comes to programming, there are substantial differences in how they work and how they are deployed.

Table 23.2 compares ActiveX controls and ActiveX documents. The table limits itself to a comparison of deploying these two technologies on Web pages, since we resolved earlier that from our perspective in this chapter, the Internet and intranets are the most likely uses for ActiveX documents.

This suggests another way of looking at ActiveX documents.

Think of your Internet browser as a window onto the Internet or an intranet. When it is displaying a Web page, what it is really doing is interpreting a simple text markup language called HTML. An advanced browser such as Microsoft's Internet Explorer or Netscape's Navigator can execute scripts that are included on the HTML page. These scripts can be in Javascript or in VBScript, but there is nothing to prevent other scripting languages from being defined.

But an Internet browser window can display other things as well. It might be able to display a directory when you are looking at an FTP site. Or perhaps an image when you ask it to display a bitmap file.

Microsoft's Internet Explorer can display ActiveX documents. Unlike an ActiveX control, which is designed to appear as an object on an HTML page, an ActiveX document is a completely independent type of object the browser can display instead of a Web page. This leads us to a staggering possibility: Because ActiveX documents support the Hyperlink object, which allows navigation among pages, it is theoretically possible to create a Web site that contains only ActiveX documents, with no HTML code whatsoever (other than perhaps a single initial page to download the server components).

Now add to this the fact that an ActiveX document has virtually all of the same capabilities as Visual Basic, including the ability to bring up additional forms, and that both the UserDocument object and the document's forms can contain additional controls. In other words: An ActiveX document is a Visual Basic application. The logical conclusion is inescapable: ActiveX documents allow you to create a site that is actually an application that runs on the client system.

Hmmm. Perhaps Carl was right about the importance of ActiveX documents after all.

On the other hand, a site created in this fashion could, at the time of this writing, only support people using Microsoft's Internet Explorer 3.01 or later on Windows 95 or Windows NT 4.0. This leaves a number of possible strategies for deploying this technology:

• You could create a site only for these people. This approach works best for Microsoft-specific sites where you don't care about people using other tools, or corporate intranets where you can dictate the client's environment.
• You could create a site in the hope that ActiveX documents will ultimately be supported by more operating systems and more browsers, and the expectation that your target audience will upgrade to the necessary tools as soon as possible.
• You could create a site in the expectation that it won't be long before everyone is running Microsoft Internet Explorer on Windows 95 or NT 4.0. (I think this is the one Microsoft would like you to choose.)
• You could create a hybrid site in which some scripting code in the HTML page detects the browser in use and sends the user to the ActiveX document pages if they have the right tools to support it. This is a good solution but does require that you effectively support two sites-one based on ActiveX documents and the other based on other technologies.
• You can stay away from ActiveX documents and go for technologies that may be less powerful but are designed to run on any possible system. (I think this is the one Netscape would like you to choose.)
• And, of course, you can choose any combination of the above.

Hmmm. Perhaps my skepticism about the importance of ActiveX documents is justified after all?

You can probably see why this chapter is short on good advice. I can see the advantages of ActiveX documents. I can see their potential. I can see they comprise a very cool technology that has the potential to bring about as great a revolution on the Internet as the invention of HTML. But I can't predict how ActiveX technology will spread to other platforms, or how important those platforms will be, or whether competing technologies might provide viable alternatives. It's just too soon to tell.

So I will leave the decision on whether or not to deploy this technology up to you, as we look into how these creatures are built.

ActiveX Document Programming

You already know 99 percent of everything you need to know in order to create ActiveX documents. So here, without further ado, is most of the other 1 percent.

Should You Use a DLL or an EXE Server?

You are already well versed in the differences between the two approaches. All of the issues that have been discussed throughout this book regarding these apply to ActiveX documents as well.

DLL servers tend to be more efficient because they run in the process space of the browser. EXE servers run in their own thread, making some background operations easier to implement. An EXE server can be configured to run as a stand-alone executable as well. (Though you will not be able to use the UserDocument, you can load and display forms during the Sub Main procedure.) A single EXE server will support all of the user documents of a given type that are loaded.

Personally, I have yet to run into a case where I wanted to use an EXE server for an ActiveX document. The most likely case where you would do so is if you wanted to control access to a shared resource, as was the case with the StockQuote server in Chapter 15.

ActiveX Document Display

ActiveX documents differ from both forms and controls in the way they are displayed.

As a programmer, you define the size of your document. You have no control over the amount of screen space that is actually allocated to your document display, but you do have complete information about the available space. If the space is smaller than the document size, the container will make it possible to view a portion of the document in a viewport. This is shown in Figure 23.1.

Figure 23.1 : ActiveX Document Viewports.

The ScaleLeft, ScaleTop, ScaleWidth, and ScaleHeight properties work as they do with forms and ActiveX controls. They reflect the coordinates of the control from the programmer's perspective. The viewport defines the area that is actually displayed. The ViewportLeft and ViewportTop properties define the location within the document area that appears in the upper left corner of the viewport area. The ViewportWidth and ViewportHeight properties define the width and height of the viewport.

The UserDocument's SetViewport method can be used to set the apparent position of the document within the viewport. It, in turn, sets the ViewportLeft and ViewportTop properties.

The UserDocument's Resize event is triggered any time the size of the document's container is changed. It occurs even if the container is larger than the current ScaleWidth and ScaleHeight settings.

If the container width is smaller than the UserDocument's MinWidth property, and the UserDocument's ScrollBars is set to display horizontal scrollbars, scrollbars will appear around the container window. This allows you to scroll the horizontal position of the document in the viewport. If the container height is smaller than the UserDocument's MinHeight property and the UserDocument's ScrollBars is set to display vertical scrollbars, scrollbars will appear around the container window. They allow you to scroll the vertical position of the document in the viewport. The HScrollSmallChange and VScrollSmallChange indicate the distance the document window scrolls when the user clicks on one of the scrollbars.

The Scroll event is triggered when the user scrolls the document within the container. If the ContinuousScroll property is True, Scroll events will be triggered as the user drags the scrollbar thumb.

The scroll.vbp project demonstrates a simple ActiveX document that displays the viewport property values and allows you to experiment with scrolling as the size of the container changes.

' Guide to the Perplexed
' Simple scrolling example
Option Explicit

Private m_ScrollCount&

Private Sub UpdateLabels()
   lblViewportLeft.Caption = ViewportLeft
   lblViewportTop.Caption = ViewportTop
   lblViewportWidth.Caption = ViewportWidth
   lblViewportHeight.Caption = ViewportHeight
   lblScrollCount.Caption = m_ScrollCount
End Sub

Private Sub UserDocument_Resize()
   Debug.Print "Resize"
End Sub

Private Sub UserDocument_Scroll()
   m_ScrollCount = m_ScrollCount + 1
   UpdateLabels
End Sub

Private Sub UserDocument_Show()
   UpdateLabels
End Sub

The Life and Times of an ActiveX Document

The Visual Basic documentation goes into quite a bit of depth regarding the life cycle of an ActiveX document. In a sense this is odd, because the key events (Initialize, InitProperties, Show, ReadProperties, WriteProperties, Hide, and Terminate) work the same way as they do with ActiveX controls. The biggest difference is that the container no longer has separate design-time and run-time modes.

While the behavior of the Microsoft Internet Explorer is very interesting as described in the VB documentation, it is also largely irrelevant. This is because you cannot assume that future versions of the browser will have the same cache size and behavior. Nor can you assume that other containers will behave similarly. So design your controls under the following assumptions:

• The container can ask your document to save itself using the WriteProperties event any time it feels like it. Generally speaking this will occur whenever you navigate away from a page containing the document and the UserDocument's PropertyChanged method has been called.
• The container can navigate to and from your document whenever it wishes. The document is reloaded from the .VBD file any time you navigate to the document.
• The container can hide and redisplay your document at any time.

Versioning

Chapter 25 will discuss the issues of versioning and preserving backward compatibility when you upgrade your control. This issue is absolutely critical with regard to ActiveX documents, because if you break backward compatibility, all of your existing .VBD files supported by that server will fail to work.

Containers

You cannot test ActiveX documents using Visual Basic. You can use the Microsoft Office Binder, but I would recommend that you use the Microsoft Internet Explorer (version 3.01 or greater). This is in following our scenario that the most likely use for ActiveX documents is on Web sites. To load an ActiveX document, simply open the .VBD file using the browser's File, Open command.

The Microsoft Office Binder has its own metaphor for dealing with ActiveX documents, calling them Sections and saving properties into .OBD (Office BinDer) files instead of the .VBD files. You should refer to your Office Binder documentation for specifics on using ActiveX documents with this container.

Menus

ActiveX documents can have a menu. However, the menu will not appear on the document page. Instead, it is merged into the container application's menu bar. In order for this to occur, you must set the NegotiatePosition option to a value other than 0.

If the top-level menu name is &Help, the menu will appear as a submenu under the container's Help menu, at least under Internet Explorer.

Error Checking

It is imperative that you trap run-time errors in your project. When a run-time error occurs, your server will stop executing. The browser will indicate that it cannot display documents that are handled by that server, typically by displaying a cross-hatched pattern over the page or an error message. The browser will not reload the server until it exits or unloads all of the cached page information, making it difficult for clients to figure out what is wrong.

The UserDocument Object

The UserDocument object is to ActiveX document servers what the UserControl object is to ActiveX controls. It is the heart of the server.

More importantly, the UserDocument works almost identically to the UserControl object. So much so, in fact, that this short section will only focus on those areas in which the two differ.

Ambient and Extender Properties

An ActiveX control is sited on a container that also contains other controls and objects. Thus the control has the need and ability to access ambient properties of the container.

An ActiveX document takes over the entire page or frame in which it is loaded. Whether this is enough of a reason to abandon the idea of ambient properties is not for me to say. But for good or for ill, the UserDocument object does not have an AmbientProperties property or Ambient object to access. Nor does an ActiveX document support an Extender object. It does, however, support a Parent property.

Parent and Other Client Properties

The UserDocument object in an ActiveX document server has a Parent property, which allows you to access properties or methods the container chooses to provide. For example, the property UserDocument.Parent.Name returns the name of the container, such as Microsoft Internet Explorer.

The Parent object and other properties that relate to the container are not accessible until the document is sited. The property will be valid after the Show event occurs (assuming it is supported under the container) but may be valid during the InitProperties and ReadProperties events, depending on the container. It will not be valid during the Initialize event.

The Parent property provides access to the object model of the container. This can provide your server with a great deal of functionality, depending on the container. Specifics of individual containers are beyond the scope of this book. The object model for the Microsoft Internet Explorer can be found in the ActiveX SDK, which is available from Microsoft.

Naturally, any code you write that uses the container's object model will be highly container-dependent.

Property Persistence

The initial .VBD document file that is created with your ActiveX document server is empty. It essentially contains nothing more than the information needed to create a default document. Every time this document is loaded, the UserDocument's InitProperties event is triggered. It is only after information has been written into the document that the ReadProperties event will be triggered. Once that happens, the InitProperties event will not be triggered again for that particular .VBD document file.

The container will only try to write out properties using the WriteProperties event if the UserDocument object's PropertyChanged method has been called for the document. This differs from ActiveX controls where the InitProperties event occurs only once, and that in the development environment.

Documents downloaded from a Web site using a browser cannot be saved directly back to the site, and it is not clear what kind of applications can benefit from having a user modify a downloaded ActiveX document and save it locally. This suggests two likely scenarios with regard to your deployment of ActiveX documents on a Web site:

• The blank document approach-There is no requirement that an ActiveX document save persisted information at all. This is especially true on documents downloaded through the Internet. The document server is, after all, a fully functional program, and there are any number of possible applications that do not require the use of properties at all. With this approach, the InitProperties event will occur every time the document is loaded.
• The predefined document approach-With this approach you provide your server with two different operating modes. One is an edit mode, which is triggered when the empty document is loaded as indicated by the InitProperties event. The other is a standard mode, which is indicated by the ReadProperties event. In edit mode, you would open the file locally on your system, edit the properties, and save the changes when you are done. In standard mode, the document might be downloaded through a Web server. The ActiveX server loads properties during the ReadProperties event and disables any options that could change the property values. This approach is demonstrated in the realty example in Chapter 24.

Naturally, you can use any combination of the two approaches. The most important thing is that you consider how you wish your ActiveX document to be used and support it by handling the InitProperties and ReadProperties events accordingly.

Tips and Tricks

Here are some additional techniques you can use with ActiveX Documents.

You can set the MinHeight and MinWidth properties to a very large value to force scrollbars to always be displayed.

Remember that you control the appearance of the document. Let's say you need a document with 100 text boxes in a vertical column (not that you would ever really want to do this). You could try to create one enormous document. A better approach would be to use a control array to create only enough text boxes to fill the available viewport, then turn on the scrollbars. When the user scrolls, you can programmatically redefine the meaning of the text boxes that are visible to make them appear as if they had scrolled, then use the SetViewport property to force the document to appear correctly in the window.

An ActiveX document can appear in a browser frame as well as in an independent window. This allows you to use any Web designer to create the navigation portion of your site (the links between the various pages), instead of coding navigation links into the document server. You'll see how this works in Chapter 24.

The Show event occurs after the document is fully sited on the container. It also occurs any time you return to the page after moving to another page. You can improve your document's performance by performing any initialization necessary the first time the Show event is called, then setting a module or static variable to indicate that the initialization is complete so you need not repeat it on subsequent Show events.

Visual Basic includes a wizard that does much of the work of converting a stand-alone application into an ActiveX document.

Given our scenario that ActiveX documents will be used primarily on Web sites, it seems clear that our next step must be to take a closer look at how ActiveX documents can be deployed on an Internet or intranet site. This is the step that forms the basis for Chapter 24.