About Control Instantiation

How does a container bring control class code (binary executable code) into memory and instantiate a control of that class?

There are two cases of concern here:

1. The control's class code is on the client computer already (or somewhere in the name space addressable through the registry on that computer). Therefore, the document needs only the CLSID of that class code because COM/OLE provides mapping from CLSID to code bits using the registry. A container generally creates a control directly using the CLSID with CoCreateInstance.
2. The control's class code is located somewhere other than on the client computer, possibly on another Internet site, and must be brought to the client computer before a control of that class can be instantiated.

This article only concerns itself with scenario 1 above, because the purpose of "code download" described in scenario 2 is to install a control on the client computer so that scenario 1 works.

The next three sections describe the issues for instantiation at author, publish, and run time.

Author Time Instantiation

A designer of a document or page will use the user interface functionality of the authoring tool to decide which object or control to insert into a document, ultimately ending up with a CLSID for the object or control. The authoring tool is responsible for providing the browsing capabilities to locate objects and controls wherever they may be, in the local name space or on some other Web location. For more information on standards related to browsing available object and control classes, see the user interface guidelines.

When a control's CLSID is known, the authoring tool simply uses standard COM/OLE instantiation (using CoCreateInstance, OleCreate, and so on) to instantiate the control. In this case, the authoring tool will need to include the control's CLSID when saving the document persistently. Handling other possibilities is still under consideration.

Otherwise, the authoring tool treats each control instance in exactly the same manner: calling methods, setting properties, attaching event handlers, specifying layout, and so on.

Saving a Control at Publish Time

At publish time, the authoring tool must create a document, in HTML or another format, that describes the exact source of each control's class code, because it will be referenced at run time, in addition to each control's instance data.

If the code is assumed to be on the client computer along with the browser, the authoring tool need only store the CLSID for the control class (the CLASSID attribute in HTML) in addition to the control's properties and persistent data, as described below. Such would be the assumption for standard system-provided control classes as well as implementations that the document will manage in its own code repository.

If the control's class code will be found at another Internet site at run time, the authoring tool must save the URL for that site. This can be done by saving the URL text directly (as the CODE attribute in HTML).

If the document incorporates custom control classes that are on the author's computer at publish time, but may not be on each client computer at run time, the authoring tool must facilitate the placement of the class code (according to license restrictions) on an appropriate Internet site, converting the CLSIDs of the control instances in the document into the appropriate monikers and then saving the monikers in the document.

In addition to each control instance (CLSID/moniker and the control's instance data), the authoring tool, at publish time, also saves its own "extended properties," which a control instance itself never deals with, such as Name, Width, Height, Align, and so on. Documents stored in their own formats use whatever data formats they want; documents saved in HTML must follow the guidelines described in HTML standards.

Run-Time Instantiation

An Internet browsing tool, when it wants to view a document, will generally activate the necessary viewer for that document type, which may be itself (in HTML cases, for instance) or some other view through DocObjects. The viewer then loads the document, re-creating the control instances therein according to the prioritization scheme determined at author time.

"Re-creating a control" means creating a previously saved instance of a control so that some persistent data for that control exists in the document or somewhere else. In the OLE model, instance data always has an associated CLSID—thus, the container knows which class code it must have to instantiate an uninitialized control using the CLSID directly (CoCreateInstance, OleLoadFromStream, and so on). Once the container creates that instance, it initializes the instance with whatever persistent data was previously saved through the Load member of some IPersist* interface. A later section in this article covers exactly where this persistent data comes from and which interfaces are involved.

In some cases, the class code for a control and its instance data resides in other locations named with monikers (or URLs, which can be turned into URL monikers as is the case with the CODE attribute in HTML). In this case, the container must first retrieve the control's class code and then proceed with creation and initialization as described above.

As with initial creation, the container now has an interface pointer to an initialized control that is generally ready for use (depending on the internal state of the control as discussed in a later section). At this time, a container may have other properties in its storage that lay outside the control's own persistent image (such as PARAM fields in HTML). In that case, it sends these property values to the control after the control has returned from IPersist*::Load.