How to ceate the KBBar .NET Internet Explorer tool band in Visual C++ .NET 2003 or in Visual C++ 2005 (821793)


The information in this article applies to:

  • Microsoft .NET Framework 1.1
  • Microsoft Visual C++ 2005 Express Edition
  • Microsoft Visual C++ .NET (2003)
For a Microsoft Visual C++ 6.0 version of this article, see 246234.

SUMMARY

This article discusses the KBBar .NET Microsoft Internet Explorer tool band sample that was developed in Microsoft Visual C++ .NET 2003. This article also contains a link to a downloadable sample project, and explains how you can use the KBBar .NET tool band. This article also explains important issues that you may have to consider while developing Internet Explorer tool bands.

INTRODUCTION

The KBBar .NET Internet Explorer tool band sample demonstrates how to host a combo box control and two button controls on the tool band. The KBBar .NET tool band uses the IWebBrowser interface of the browser to explore and to implement the search functionality in the Microsoft Developer Network (MSDN) Web site and in the Microsoft Knowledge Base (KB).

The KBBar .NET Internet Explorer tool band sample demonstrates how to deal with complicated issues such as keystroke problems, navigation problems, and registration problems while developing Internet Explorer tool bands.

The KBBar .NET Internet Explorer tool band sample uses the features of Microsoft Visual C++ .NET 2003 or of Microsoft Visual C++ 2005 and the features of the Microsoft .NET Framework 1.1 or later. You must have Visual Studio .NET 2003 and the .NET Framework 1.1 or Visual Studio 2005 and the .NET Framework 2.0 installed on your computer to use this sample.

The following file is available for download from the Microsoft Download Center:

DownloadDownload the NewKB.exe package now.

Release Date: June 16, 2004

For additional information about how to download Microsoft Support files, click the following article number to view the article in the Microsoft Knowledge Base:

119591 How to Obtain Microsoft Support Files from Online Services

Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on security-enhanced servers that help to prevent any unauthorized changes to the file.

back to the top

Usage

The KBBar .NET Internet Explorer tool band sample has been kept intentionally simple. It contains two button controls and a combo box control. The buttons move to the MSDN Web site and to the MSDN Web Workshop site. These locations are hard-coded. A ToolTip is provided for each button control.

You can use the combo box control to search the KB either by using the article number or by using a set of keywords.
  • To search by using keywords, type the keywords in the combo box control, and then press ENTER.
  • To search for an article number, type the article number preceded by a number sign (#) character, and then press ENTER. For example, to view KB article 234234, type #234234 in the combo box control.
The combo box control stores all searches that are entered in it. You can use the drop-down list to select an earlier search, and then you can press ENTER to run that search again.

back to the top

Architecture

The KBBar .NET Internet Explorer tool band sample has a solution file that contains two Windows Control Library (.NET) projects. These projects are KBBar and SampleKB. The KBBar project is a Windows Control Library (.NET) project that defines the base functionality of the KBBar .NET band object. The SampleKB project is a Windows Control Library (.NET) project that uses the base functionality that the KBBar .NET band object provides, and then adds more interface elements and more functionality.

The KBBar project defines the base functionality of the band object. This project implements the different Component Object Model (COM) interface methods that are necessary for creating the band objects. This project also handles the registration and the unregistration of different types of band objects such as the following:
  • Vertical Explorer Bars
  • Horizontal Explorer Bars
  • Explorer Toolbars
  • Taskbar Toolbars
You may have to customize the Register function and the Unregister function by adding the appropriate component categories according to the type of band object that you are trying to create. This sample currently handles only an Explorer Toolbar band object.

The SampleKB project creates a new control class that is derived from the KBBarControl class. This project instantiates the band object and sets the band object's attributes such as the Title attribute, the BandObjectStyle attribute, and the HelpText attribute. The SampleKB project adds different user interface (UI) elements to the derived control class and the handles the functionality of these elements. The derived control class also handles functionalities such as the following:
  • Searching the KB for articles by using different keywords or by using the article number
  • Providing ToolTips for button controls
  • Providing the autocomplete feature for the combo box control
back to the top

Registration procedure

The KBBar .NET Internet Explorer tool band sample handles the registration of the KBBar .NET tool band. To register the KBBar control, follow these steps:
  1. After you have downloaded the sample, extract the files to a local drive on your computer. This action creates a folder that is named NewKB on your computer. The NewKB folder contains folders that are named KBBar and SampleKB. These folders contain other files and folders.
  2. Start Visual Studio .NET 2003, and then open the KBBar.sln solution file that is located in the KBBar folder.
  3. On the Build menu, click Rebuild Solution to build the solution. The DLLs are registered automatically.
  4. Start Microsoft Internet Explorer.
  5. If the KBBar .NET tool band does not appear in the toolbar area in Internet Explorer, use one of the following methods to view the KBBar .NET tool band:
    • On the View menu, click Toolbars, and then click KBBar .NET.
    • Right-click in the toolbar area, and then click KBBar .NET
    When your mouse pointer is over the KBBar .NET menu command, notice that the Shows/Hides KBBar text appears in the status bar.
back to the top

Sections of interest

The most important sections in the KBBar .NET Internet Explorer tool band sample are the following:back to the top

ComInterops.h file

The ComInterops.h file includes the COM interface method definitions that you must define and implement to create a band object. Internet Explorer requires that all band objects implement a set of COM interfaces such as the IObjectWithSite interface, the IDeskBand interface, and the IPersistStream interface. These interface declarations are available in the form of C++ classes and Microsoft Interface Definition Language (MIDL) interfaces. Therefore, before you can use these interfaces, you must convert these declarations to one of the programming languages that uses the Microsoft .NET Framework.

This file also contains many structure data types and many enumerated data types that these interfaces use. You can use a System::IntPtr type for a HWND type. Also, you can use an Object type for an IUnknown type or for a void type as they are used in this file.

back to "Sections of interest"
back to the topDESKBANDINFO structure The DESKBANDINFO structure contains information and receives information for a band object. The DESKBANDINFO structure is used together with the IDeskBand::GetBandInfo method. The DESKBANDINFO structure must be a __value type to make the band object title appear on the KBBar control in Internet Explorer.

back to "Sections of interest"BandObjectStyle attribute The BandObjectStyle attribute is an enum type that defines different styles of band objects that you can create. You can use any combination of styles. The style is passed from the SampleKB project when you create an instance of the BandObjectAttribute class. The KBBar .NET Internet Explorer tool band sample uses the ExplorerToolbar style to create the KBBar control.

back to "Sections of interest"BandObjectAttribute class The BandObjectAttribute class is derived from the System::Attribute class. The BandObjectAttribute class defines the custom band object attribute class. This class contains three members, Name, Style, and HelpText. The value of the Name member appears as the menu text under Toolbars on the View menu in Internet Explorer. The value of the HelpText member appears as the status bar message when you select the menu text under Toolbars on the View menu.

back to "Sections of interest"
back to the top

AssemblyInfo.cpp file

Every time that you rebuild your project, Microsoft Visual Studio .NET generates a new version of the assembly. To avoid this behavior, the AssemblyVersionAttribute attribute is changed to the following:
[assembly:AssemblyVersionAttribute("1.0.0.0")];
The AssemblyKeyFileAttribute attribute must have the full path of the strong name key file as in the following code:
[assembly:AssemblyKeyFileAttribute(S"..\\KBBar.snk")];
back to "Sections of interest"
back to the top

KBBarControl.h file

The KBBarControl.h file contains the base functionality of the KBBar .NET band object. The COM Interfaces that are defined in the ComInterops.h file are implemented in the KBBarControl.h file.

Because the KBBarControl class uses the WebBrowser class to obtain a reference to the host instance of Internet Explorer, you may have to add a reference to the Microsoft Internet Controls COM components that are defined in the SHDocVw.dll file. When you add a reference to this DLL, the Visual Studio .NET IDE creates an interop assembly for this DLL and then copies the interop assembly to your project folder.

You can use this interop assembly in your code to access the WebBrowser class as in the following code: 
// Declare the namespace.
using namespace Interop::SHDocVw;
...
// Add a reference to the host explorer.
		Interop::SHDocVw::WebBrowserClass*	Explorer;
The NavigateToURL method uses the Navigate2 method of the WebBrowser class to open the Web page in Internet Explorer.

back to "Sections of interest"
back to the topIDeskBand interface The entry point for the band object is the IDeskBand.GetBandInfo method. The GetBandInfo method implementation receives the values of the Size property, the MinSize property, the MaxSize property, the IntegralSize property, and the Title property and populates the DESKBANDINFO structure.

The DESKBANDINFO structure gives Internet Explorer information about how to display and about how to resize the band object. The ShowDW method delegates to the Control::Show method or to the Control::Hide method. The CloseDW method calls the Dispose method, and the GetWindow method returns the Handle property of the control.

back to "Sections of interest"IObjectWithSite interface The IObjectWithSite interface provides a simple way to support communication between an object and its site in the container. You must have the IObjectWithSite interface to establish communication with the host Internet Explorer process. In the SetSite method, the control tries to obtain a reference to an IWebBrowser interface that is implemented by the top-level object of Internet Explorer. The IWebBrowser interface will be available through the KBBarControl::Explorer property.

If you are creating a Taskbar toolbar or a Desk Band, you do not have to have the IWebBrowser interface. Therefore, when a pointer to the IWebBrowser interface is retrieved in the SetSite method, the KBBarControl class fires the ExplorerAttached event. Handling this event is useful when you want to add extra initialization code such as code to subscribe to Web browser events.

back to "Sections of interest"IInputObject interface The IInputObject interface is used to change UI activation and to process accelerators for a user input object that is contained in the Shell. You must use the IInputObject interface if you want your band object to participate in the processing of keyboard input. The user can move from one Internet Explorer interface object, such as the address bar or a folder view, to another by pressing TAB or by pressing SHIFT+TAB.

When it is your band object's turn to be activated or to be deactivated, Internet Explorer calls the UIActivateIO method. The implementation of this method in the KBBar project calls the Select method on one of the KBBar .NET control's child controls that acquires focus. A control is selected depending on the tab order of the controls and depending on whether the user presses TAB to move forward or presses SHIFT+TAB to move backward.

The KBBar .NET control also verifies that focus can leave the band object if the last control is selected and the user presses TAB. This logic is implemented in the TranslateAcceleratorIO method. The TranslateAcceleratorIO method determines whether the TAB key or the F6 key is pressed.

Depending on the state of the SHIFT key, the focus is moved from one child control to another by using the SelectNextControl method. The last parameter of the SelectNextControl method is made false to avoid cycling through controls in a continuous loop from the first control to the last control or, if the SHIFT key is pressed, from the last control to the first control. If there is no next control, the call to the SelectNextControl method returns zero to signal to Internet Explorer to process this command. Internet Explorer processes this command and then changes focus to the appropriate UI object.

back to "Sections of interest"Register and Unregister functions The Register function is a Static function that has the ComRegisterFunctionAttribute attribute. The Regasm.exe tool calls the Register function when the assembly is registered as a COM server. The Register function verifies whether the BandObjectAttribute attribute is present in the input parameter of the Register function. If the BandObjectAttribute attribute is present, the Name property, the Style property, and the HelpText property of the attribute are used to create the correct registry settings.

To make the KBBar .NET control an Internet Explorer toolbar, you must register the class identifier (CLSID) of the KBBar .NET control under the SOFTWARE\Microsoft\Internet Explorer\Toolbar registry subkey.

Similarly, the Unregister function handles the removal of keys from the registry when you unregister the assembly.

You must customize the Register function and the Unregister function by adding the correct component categories for different types of band objects that you are creating. For example, if you are creating a Vertical Explorer Bar band object, you must register the CATID_InfoBand component category. The following code registers the CATID_InfoBand component category:
if( 0 != (style & BandObjectStyle.Vertical) )
{
rkCat->CreateSubKey(S"{00021493-0000-0000-C000-000000000046}");
rkCat->CreateSubKey(S"CATID_InfoBand");
}
back to "Sections of interest"
back to the top

SampleKBControl.h file

The SampleKBControl.h file contains the implementation of UI elements. The SampleKBControl class is derived from the KBBarControl class. The SampleKBControl class instantiates the band object and sets the attributes of the band object.

back to "Sections of interest"
back to the topSampleKBControl function The SampleKBControl function is the Constructor function. The SampleKBControl function initializes the KBBar .NET control. The Title property of the KBBar .NET control is set in the InitializeComponent method. The SampleKBControl function creates a ToolTip object and associates the ToolTip object with the two button controls to show a ToolTip at runtime. A GotFocus event handler for the combo box control is also added. The GotFocus event handler prevents the focus problems that may occur while you are developing band objects.

back to "Sections of interest"HasFocusIO method The HasFocusIO method is an overridden method of the KBBarControl::HasFocusIO method. The HasFocusIO method notifies Internet Explorer that the band object has focus to process keyboard events. You must use this overridden method to avoid focus problems in the band object.

back to "Sections of interest"TranslateAcceleratorIO method The TranslateAcceleratorIO method is an overridden method of the KBBarControl::TranslateAcceleratorIO method. You must use this overridden method to avoid the BACKSPACE key problem and other navigation key problems in the combo box control in the KBBar .NET band object.

back to "Sections of interest"GotFocus method You may experience focus problems while you are developing the KBBar .NET band object. For example, Internet Explorer may not be able to determine if the band object currently has focus.

To avoid this problem, you can use the GotFocus method. The GotFocus method calls the GotFocus method of the KBBarControl class. In the KBBarControl::OnGotFocus method, the IInputObjectSite::OnFocusChangesIS method is called to inform Internet Explorer that the KBBar .NET band object has focus.

back to "Sections of interest"
back to the top

Registration of band objects

Band objects are COM components. For the .NET Framework to find an assembly that implements a COM component, the assembly must be either registered in the global assembly cache or located in the folder of the client application.

Two possible client applications exist for band objects, Explorer.exe and Iexplorer.exe. Explorer.exe is located in the Windows folder and Iexplorer.exe is located in the Program Files folder. Therefore, registration in the global assembly cache is the only option in this case. .NET assemblies that implement band objects must be registered in the global assembly cache. Also, all libraries that the band objects depend on, such as the KBBar.dll file, must also be put in the global assembly cache.

Because the KBBar project uses the WebBrowser class methods, the KBBar project contains a reference to the Microsoft Internet Controls COM components that are defined in the ShDocVW.dll file. You can remove the reference to this DLL. However, if you experience any problems while you are registering the DLL, you can add the reference again.

To add a reference to this DLL:
  1. In Solution Explorer, right-click the KBBar project node, and then click Add Reference.
  2. In the Add Reference dialog box, click the COM tab.
  3. In the list of COM components, click Microsoft Internet Controls, and then click Select.
  4. Click OK to close the Add Reference dialog box.
The assemblies in the global assembly cache must have strong names. You can use an .snk strong name key file to give an assembly a strong name. You can use the KBBar.snk file that is included with the downloadable sample, or you can generate a new strong name file by using the Sn.exe Strong Name Utility. If you generate a new strong name file, you must change the key file name in the code of the AssemblyInfo.cpp file.

When you add a reference to the SHDocVw.dll file, Visual Studio .NET creates an Interop.SHDocVw.dll interop assembly and then copies the Interop.SHDocVw.dll interop assembly to your project folder. You must register the Interop.SHDocVw.dll interop assembly in the global assembly cache. However, before you register the Interop.SHDocVw.dll interop assembly in the global assembly cache, you must give the Interop.SHDocVw.dll interop assembly a strong name.

To give the Interop.SHDocVw.dll interop assembly a strong name:
  1. In Solution Explorer, right-click SHDocVw under the References node in the KBBar project node, and then click Properties.
  2. In the Interop.SHDocVw Property Pages dialog box, expand Configuration Properties, and then expand Managed Wrapper.
  3. Click General.
  4. In the Strong Name Type property, click to select the Key File (/keyfile:FileName) option from the drop-down list.
  5. In the Strong Name property, type the strong name key file including the path, and then click OK.

Note You can also use the Aximp.exe tool for signing an assembly by using a strong name.

You can automatically register the assemblies in the global assembly cache by setting the PostBuildEvent configuration property of the projects correctly. The following commands are run in the PostBuildEvent configuration property of the KBBar project:
cd $(SolutionDir)$(ConfigurationName)
gacutil /if KBBar.dll
gacutil /if Interop.SHDocVw.dll
The following commands are run in the PostBuildEvent configuration property of the SampleKB project:
cd $(SolutionDir)$(ConfigurationName)
gacutil /if SampleKB.dll
regasm SampleKB.dll
To unregister the KBBar .NET tool band, follow these steps:
  1. Open a Visual Studio .NET 2003 or Visual Studio 2005 command prompt.
  2. Move to the directory that contains the SampleKB.dll file.
  3. Type the following command at the command prompt, and then press ENTER:
    regasm SampleKB.dll /unregister
The types are then unregistered from the assembly.

back to the top

REFERENCES

For more information about how to develop band objects for Microsoft Internet Explorer, visit the following MSDN Web site:

http://msdn.microsoft.com/library/en-us/shellcc/platform/Shell/programmersguide/shell_adv/bands.asp

For more information about keystroke problems that may occur when you use the WebBrowser control, visit the following Microsoft Web site:

http://www.microsoft.com/mind/0499/faq/faq0499.asp

For additional information, click the following article numbers to view the articles in the Microsoft Knowledge Base:

196339 SAMPLE: WebBand.exe hosts WebBrowser control in an Explorer band


313666 PRB: "Assembly generation failed" error message when you try to build a managed DLL without a strong name

back to the top
Modification Type:MajorLast Reviewed:1/17/2006
Keywords:kbToolbar kbDLL kbControl kbCOMInterop kbComCtrls kbBandObjs kbinterop kbDownload kbSample kbcode kbinfo KB821793 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.