Adding and Reporting ActiveX Controls

A designer calls the host's IDesignerToolboxSite::AddControl method to inform it of the ActiveX controls the designer contains. After calling QueryService for a pointer (piToolboxSite) to the IDesignerToolboxSite interface, the designer can call the method as follows:

hr = piToolboxSite->AddControl (rclsid);

The rclsid parameter supplies the CLSID of the ActiveX control being added.

The designer calls this method in the following situations:

• When the designer is loaded, it calls AddControl for each ActiveX control it contains. Note, however, that if the value of the DISPID_AMBIENT_INTERACTIVE property is FALSE, the designer need not call the method because the designer instance is only temporary.
  
  
• Whenever a user drops a control onto the designer, the designer calls AddControl to ensure that the host adds the control to the toolbox. If the control is already in the toolbox, no error occurs.
  
  
• When the designer chooses to make an ActiveX control available for use in the project, it calls AddControl to place that control in the host's toolbox. This method is the only way a designer can add a control for general use; all its toolbox items listed under the DesignerToolbox registry subkey are intrinsic designer-specific controls.

Controls added with this method appear on the General toolbox tab in Visual Basic 6.0, not on the designer's own tab (if it has one).

To find out which controls are currently on the designer, the host calls the designer's IDesignerToolbox::GetControlsInUse method. The method is declared as follows:

HRESULT GetControlsInUse(
         DWORD * pcControls, 
         CLSID ** prgClsids);

In pcControls, the host passes a pointer to a location in which the designer returns the number of controls it currently contains. In prgClsids, the host passes a pointer to a location in which the designer returns a pointer to an array of the class identifiers (CLSID values) of all these ActiveX controls.

For example, a form designer might maintain a list of data structures, ControlClasses, each of which describes a class of controls on the designer. Each data structure includes the CLSID, ProgID, and the number of methods, properties, and events for a control class (for example, a Rich Textbox control). Each instance of the control on the form designer shares the data structure.

In GetControlsInUse, the designer traverses this list of data structures and reports the class identifiers (CLSID values) of all its ActiveX controls:

MyDesigner::GetControlsInUse(DWORD * pcControls, CLSID ** prgClsids)
{
   ULONG cClsids;
   rgClsids = new CLSID[m_cControlClasses];
   GatherClassIdsFromList(ControlClasses, &rgClsids, &cClsids);
   *prgClsids = rgClsids;
   *pcControls = cClsids;
   return (S_OK);
}

The designer must allocate the CLSID array using the COM memory allocator.

The host calls GetControlsInUse whenever it requires information about the controls on the designer. Typically, the host gets this information when it closes the designer in the IDE; it can also request the information to determine whether a particular ActiveX control is being used anywhere in the current project.