How to: Provide Custom Toolbox Items By Using Interop Assemblies

  • Article

Note

The recommended way to add custom controls to the Toolbox is to use the Toolbox Control templates that come with the Visual Studio 10 SDK. This topic is retained only for backward compatibility, and for adding existing controls to the Toolbox.

For more information on creating toolbox controls by using the templates, see How to: Create a Toolbox Control That Uses Windows Forms and How to: Create a Toolbox Control That Uses WPF.

A VSPackage based on an interop assembly can extend Visual Studio Toolbox functionality by adding ActiveX controls.

For a list of standard Visual Studio Toolbox Clipboard formats, see Toolbox (Visual Studio SDK).

For information on how a VSPackage manages the Toolbox using Visual Studio SDK, see Managing the Toolbox.

For information on managing the Toolbox through automation, see How to: Control the Toolbox.

Procedures

Items added to the Toolbox should implement the standard Toolbox Clipboard formats unless the VSPackage adding the items acts as a Toolbox item provider — providing implementation support for the new format.

To implement Toolbox control

  • A Toolbox item provided by VSPackage implemented in unmanaged code must either implement an IDataObject object or be an ActiveX control — from which the environment can obtain an IDataObject object.

    For more information about implementing the IDataObject object to support the Toolbox, see IDataObject, TBXITEMINFO, and FORMATETC.

To add interop assembly-based controls to the Toolbox

  1. Obtain instances of :

    1. IVsToolbox2, which supports adding controls and sections (tabs) to the Toolbox and controlling other aspects of the Toolbox configuration.

    2. IVsToolbox3, which provides support for localization and Visual Studio settings persistence.

    Note

    The IVsToolbox2 interface inherits from the IVsToolbox interface. IVsToolbox3 does not derive from IVsToolbox2 and does not implement its methods.

    IVsToolbox3 and IVsToolbox2 are obtained by calling the QueryService method on the SVsToolbox service by using the service ID of SID_SVsToolbox.

    The interface ID IID_IVSToolbox2 is used to obtain IVsToolbox2, and the interface ID IID_IVSToolbox3 returns IVsToolbox3.

    In the sample below, the IVsToolbox2 interface is obtained with a QueryService and the IVsToolbox3 interface by calling QueryInterface on the IVsToolbox2 interface.

    extern CComModule _Module;
CComPtr<IVsToolbox2> srpTbx2;
CComPtr<IVsToolbox3> srpTbx3;
hr = _Module.QueryService(SID_SVsToolbox, IID_IVsToolbox2, (void**) &srpTbx2));
hr = srpTbx2->QueryInterface( IID_IVsToolbox3, (void **)&srpTbx3)

  2. Use instances of the IVsToolbox2 and the IVsToolbox3 interfaces to add tabs (sections) and controls to the Toolbox.

    In the sample below, a new tab is added with a localized name using the AddTab method.

    As this localized name is not invariant, a non-localized invariant name (in this case L"HTML") is set by a call to the SetIDOfTab method.

    If the toolbox tab already exists, AddTab2 returns E_FAIL, in which case it is assumed that the tab was properly added before an attempt is made to retrieve the invariant name.

    If a tab has been successfully added, then an IDataObject-based control is added to the Toolbox; otherwise an error is returned.

    CComBSTR sbstrID;
hr = srpTbx2->AddTab2((WCHAR*)szwDisplayTabName, *pclsidPackage);
if ( hr == S_OK) {
    sbstrID =L"HTML";
    hr = srpTbx3->SetIDOfTab( (WCHAR*)szwDisplayTabName, sbstrID);
}else{
    hr = S_OK;
    hr = srpTbx3->GetIDOfTab( (WCHAR*)szwDisplayTabName, &sbstrID );
    
}
if ( hr = S_OK){
    hr=srpTbx2->AddItem(tbxItem, &tinfo, bstrLabel);
}
return hr;

In addition to adding to the Toolbox itself, a VSPackage can be configured as a Toolbox data provider and can be used to extend the drag-and-drop support to the Visual Studio IDE. This allows arbitrary clipboard formats to be exposed to the Toolbox and editors.

To configure VSPackage as a Toolbox Item Provider

  1. Register the interop-based VSPackage as a Toolbox item provider.

    For more information on registering as a Toolbox provider, see Registering Toolbox Support Features.

  2. Register as supporting custom Toolbox Clipboard formats.

    Interop-based VSPackage supporting controls that do not implement all the standard Toolbox Clipboard formats or implement a custom Toolbox Clipboard format must:

    1. Register the Toolbox Clipboard formats that they do support. For more information, see Registering Toolbox Support Features.

    2. Create a class implementing the IVsToolboxDataProvider and IVsToolboxDataProvider2 interfaces.

      Note

      The IVsToolboxDataProvider and IVsToolboxDataProvider2 interfaces should not be implemented on the same class that implements the IVsPackage interface.

    3. Programmatically inform the Toolbox that a specific implementation of the IVsToolboxDataProvider and IVsToolboxDataProvider2 interfaces provides support for custom data formats with either of the equivalent methods—RegisterDataProvider or RegisterDataProvider.

      Calling the RegisterDataProvider method is typically done in the implementation of the SetSite method or in the OnCreate handler method for when the VSPackage becomes active.

        CComPtr<IVsToolboxDataProviderRegistry> pTB;
  if (SUCCEEDED (hr = pServiceProvider->QueryService(SID_SVsToolboxDataProviderRegistry, IID_IVsToolboxDataProviderRegistry, (PVOID*)&pTB)) && pTB != NULL)
  {
      CustToolboxDataProvider* pDP = new CustToolboxDataProvider;
      if (pDP)
      {
          pDP->AddRef();
          VSCOOKIE dwDPCookie; //UNDONE: pass NULL instead of ptr to the cookie when RegisterDataProvider allows it.
          pTB->RegisterDataProvider((IVsToolboxDataProvider*)pDP, &dwDPCookie);
          pDP->Release();
      }
      else
      {
          hr = E_OUTOFMEMORY;
      }
  }

For a list of standard Visual Studio Toolbox Clipboard formats, see Toolbox (Visual Studio SDK).

See Also

Tasks

Advanced Toolbox Control Development

How to: Control the Toolbox

Concepts

Registering Toolbox Support Features

Managing the Toolbox

Other Resources

Toolbox (Visual Studio SDK)

Toolbox Walkthroughs