Creating the Run-Time Object

When the end user issues commands to build or run the application, Visual Basic calls several interfaces in the designer to create a run-time object.

First, Visual Basic calls IProvideClassInfo or IProvideDynamicClassInfo to get the type information it needs to create the object.

Next, before compiling the application or shifting into run mode, Visual Basic checks the value of the DESIGNERFEATURE_BEFORERUN flag in the registry. If the flag is set, indicating that the designer implements the IDesignerDebugging::BeforeRun method, Visual Basic calls this method.

In addition, Visual Basic asks the ActiveX designer to save the prototypical instance state for the run-time object. If the visual designer implements the IActiveDesigner interface, Visual Basic calls its SaveRuntimeState method to save the data. If not, Visual Basic uses the Save method of the visual designer's persistence interface, in the following order of preference:

• IPersistStreamInit
  
  
• IPersistStream
  
  
• IPersistStorage

Persistence and the IActiveDesigner interface are described in Chapter 7, "Persisting, Saving, and Debugging an ActiveX Designer."

On the Debugging tab of the Project Properties sheet, the user can denote one of the designers in the project as the Start component. If the user does so, Visual Basic calls that designer's IDesignerDebugging::GetStartupInfo method to determine which host to launch for the debugging session.

The exact steps that Visual Basic follows to create the ActiveX designer's run-time object depend on the requirements of the designer itself, as specified in the DesignerFeatures key in the registry.

The following is a sample registry entry for an ActiveX designer:

HKEY_CLASSES_ROOT\CLSID\<clsid>
    \MiscStatus
           OLEMISC_SETCLIENTSITEFIRST
     \DesignerFeatures
     Required
           DESIGNERFEATURE_PREDECLAREDID
           DESIGNERFEATURE_CANBEPUBLIC
           DESIGNERFEATURE_DELAYEVENTSINKING

In the sample, the designer sets three required designer flags and no optional flags. The next figure shows the steps Visual Basic takes at run time to create the run-time object for this ActiveX designer:

The following steps describe how Visual Basic creates the run-time object:

1. Calls CoCreateInstance to create a default instance of the designer, because the designer sets DESIGNERFEATURE_PREDECLAREDID in the registry. Visual Basic does not create a default instance unless this flag is set. Visual Basic passes the class ID (CLSID) saved in the registry. The designer's class factory ensures that the run-time object is properly licensed.
   
   
2. Calls IOleObject::SetClientSite, because the designer specifies OLEMISC_SETCLIENTSITEFIRST. If the designer does not set this flag, Visual Basic does not set the site until the persistent data are successfully loaded. If the designer instead sets DESIGNERFEATURE_DONTSITE, Visual Basic does not site the designer unless it is public and a different host explicitly sites it.
   
   
3. Calls the Load method of the designer's persistence interface to load persistent data for the new object.
   
   
4. Calls IActiveDesignerRuntime::SetSite, because the designer sets DESIGNERFEATURE_DELAYEVENTSINKING in the registry. This method sets the site through which the designer can later connect events. If the designer did not set the flag, Visual Basic would instead use the designer's connection point interfaces to connect events immediately.
   
   
5. Calls IProvideDynamicClassInfo::GetDynamicClassInfo to get the designer's type information. If the designer does not support dynamic type information, Visual Basic calls methods of the IProvideClassInfo interface instead.

An end user can create additional instances of a class defined by an ActiveX designer by using the New operator in Visual Basic code. Like the Forms class, but unlike ActiveX controls and public class modules, the classes produced by ActiveX designers are private classes by default.

If the designer sets the DESIGNERFEATURE_CANBEPUBLIC flag in the registry, an end user can specify that the class is public (like ActiveX controls and public class modules). To allow a public designer to be created with the New keyword in Visual Basic, the designer must also set DESIGNERFEATURE_CANCREATE in the registry. If the designer specifies both DESIGNERFEATURE_MUSTBEPUBLIC and DESIGNERFEATURE_CANBEPUBLIC, the class must be public; an end user cannot make it private.

After execution completes, Visual Basic checks the value of the DESIGNERFEATURE_AFTERRUN flag in the registry. If the flag is set, indicating that the designer implements the IDesignerDebugging::AfterRun method, Visual Basic calls this method.