InformIT: Visual C++ 6 Unleashed > Using the Win32 WebBrowser ActiveX Control

Table of Contents

Using the Win32 WebBrowser ActiveX Control

Writing your own control or component that parses Dynamic HTML would be a daunting task. Fortunately, you don't have to. You can use the support that's already built into Internet Explorer.

One way that you can leverage Internet Explorer in your applications is to use the WebBrowser ActiveX control. The WebBrowser control encapsulates most of the interesting functionality found in a typical web browser, including

Navigation, both via hyperlink clicks and programmatically to a location named by a specified Uniform Resource Locator, also known as a URL
Viewing and printing of Web pages
History and favorite lists
Security settings for loading and executing specific types of content

The WebBrowser control is implemented as an ActiveX control that is easily added to dialog box resources, enabling you to use the control in dialog boxes and form views. The COM interfaces exposed by the WebBrowser ActiveX control are derived from IDispatch, making it easy to use the control with a variety of clients, including applications built using MFC.

Many popular applications use the WebBrowser ActiveX control to implement portions of their user interface. Microsoft Money, Microsoft Outlook, and the HTML Help viewer are just three examples of non-browser applications that use the WebBrowser ActiveX control. There are also a large number of more traditional browsing and editing applications that use the WebBrowser control, such as the AOL browser and the HoTMetaL Pro HTML editor.

The WebBrowser Control Architecture

The WebBrowser control is hosted inside MSHTML.DLL, one of the DLLs distributed as part of Internet Explorer. When Internet Explorer is updated, the functionality provided by the WebBrowser control is also updated. However, an update of the Internet Explorer browser will not break any applications using the WebBrowser ActiveX control, as the interfaces between the control and the application do not change.

The interfaces used when interacting with the WebBrowser control are defined in ExDisp.IDL, the interface definition file for Internet Explorer components. This file is located in the Visual C++ include directory, which by default is located in the \VC98\Include subdirectory under the location where Visual C++ was installed.

The interface used to control the WebBrowser control is IWebBrowser2, which is derived from IWebBrowserApp. IWebBrowserApp is derived from IWebBrowser, an older interface introduced with Internet Explorer 3.0. In turn, IWebBrowser is derived from IDispatch, the interface used to implement all Automation interfaces in COM.

When a WebBrowser control is added to your project, a wrapper class named CWebBrowser2 is created. This class is used to manage interaction with the WebBrowser control.

WebBrowser Control Properties and Methods

The IWebBrowser2 interface has a large number of properties and methods, which are documented in the online help. Some of the most commonly used properties are described in Table 12.1.

Table 12.1. Commonly Used Properties

Property	Description
`Document`	A pointer to the active Document interface
`LocationName`	The name of the current browser location
`LocationURL`	The path to the current browser location
`Visible`	Determines if the browser is visible
`StatusBar`	Determines if the status bar is visible or hidden
`StatusText`	The text displayed on the status bar

Additional properties can be found in the online documentation, or by reading ExDisp.IDL.

When MFC is used to access control properties, accessor functions are created for each property. Two functions are created for properties that can be both read and written; one function is used to read the property, the other function is used to write to the property. For example, the read-only Document property is managed by just one CWebBrowser2 member function:

LPDISPATCH CWebBrowser2::GetDocument()

The Visible property can be read and written, and so it's managed by two functions:

BOOL CWebBrowser2::GetVisible()
void CWebBrowser2::SetVisible(BOOL bNewValue)

The functions exposed by the CWebBrowser2 class are slightly abstracted from the raw IDL that you would see in ExDisp.IDL. This simplifies the work that is required to use these interfaces in an MFC program. For example, the Visible property actually has a type of VARIANT_BOOL, a VARIANT type which is awkward to use in a C++ program. The MFC accessor functions enable you to use the more convenient BOOL variable type.

There are also a large number of methods exposed by the WebBrowser control. These functions are used to perform actions such as navigating to a new location and reloading the current page. The most commonly used methods are listed in Table 12.2.

Table 12.2. Commonly Used WebBrowser Methods

Method	Description
`GoBack`	Navigates to the previous location in the history list
`GoForward`	Navigates to the next location in the history list
`GoHome`	Navigates to the home URL
`Navigate`	Loads a specific URL
`Navigate2`	Loads a specific URL or special folder
`Refresh`	Forces the current location to be reloaded

Additional methods can be found in the online documentation, or by reading ExDisp.IDL.

The first two methods in Table 12.2 work in conjunction with the history list, and have no parameters. The history list maintains the list of recently visited locations, and these functions enable a user to scroll forward and backward through this list of URLs.

Navigate and Navigate2 are relatively complex methods that allow you to specify where the WebBrowser should navigate, as well as how the navigation is to be carried out. Navigate2 extends the Navigate method by allowing special folders, such as Desktop or My Computer to be loaded.

The MFC wrapper around the Navigate method is declared as:

void CWebBrowser2::Navigate(LPCTSTR URL,
                            VARIANT* Flags,
                            VARIANT* TargetFrameName,
                            VARIANT* PostData,
                            VARIANT* Headers);

The Navigate method has five parameters:

A URL specifying the location to be loaded.
The address of a VARIANT containing navigation flags, if any. Possible values for this parameter are discussed below.
The address of a VARIANT containing the name of an HTML frame that serves as the navigation target. To load the document into the current frame, pass an empty VARIANT for this parameter.
The address of a VARIANT containing HTML POST data associated with the navigation; this data will be sent to the server. In most cases, an empty VARIANT is passed for this parameter.
The address of a VARIANT containing any optional header information to be sent to the server. In most cases, an empty VARIANT is passed for this parameter.

The following navigation flags can be passed for the second parameter to Navigate or Navigate2:

navOpenInNewWindow specifies that the location should be opened in a new instance of Internet Explorer.
navNoHistory specifies that the new location should not be added to the history list.
navAllowAutoSearch specifies that an automatic search is to be performed if the location can't be found. Autosearch works by appending common root domains, such as COM, EDU, and GOV to the requested URL. If the location still isn't found, the URL is passed to a search engine defined in the system registry.
navBrowserBar specifies that the current Internet Explorer browser bar should be used to navigate to the desired URL.

A VARIANT initialized to VT_EMPTY may be passed for any of the last four parameters. The proper way to initialize a VARIANT as empty is to use the VariantInit function:

VARIANT varEmpty;
VariantInit(&varEmpty);

Alternatively, you can use the COleVariant class, which automatically initializes a variant for you:

COleVariant varEmpty;  // ctor initializes variant as empty

More information about handling variants can be found in Chapter 24.

An example of a function that uses the Navigate function is shown below:

void CWebCtlDlg::OnGotoHelp()
{
    COleVariant varEmpty;
    // m_wb is an instance of the WebBrowser control
    m_wb.Navigate("http:\\www.codevtech.com\\help.htm",
                  &varEmpty,
                  &varEmpty,
                  &varEmpty,
                  &varEmpty);
}

As discussed earlier, the Navigate2 method enables navigation to special folder locations, such as My Computer. The MFC wrapper for Navigate2 differs slightly from Navigate:

void CWebBrowser2::Navigate2(VARIANT* URL,
                             VARIANT* Flags,
                             VARIANT* TargetFrameName,
                             VARIANT* PostData,
                             VARIANT* Headers);

As you can see above, the parameter list for Navigate2 is slightly different than Navigate. The first parameter is the address of a VARIANT, which enables you to pass information about special folders in the form of a pointer to an item identifier list, also known as a PIDL, in addition to basic URL strings. The remaining parameters for Navigate2 are identical to the parameters used by Navigate.

In order to navigate to a special folder location, you must first create an ITEMIDLIST structure, then pack the structure into a VARIANT containing a safe array, and then pass the VARIANT address to the Navigate2 function. In order to perform these steps, you need to perform some grungy low-level work using the ITEMIDLIST, SAFEARRAY, and VARIANT structures. The steps required are shown later in this chapter, in the WebCtl project.

WebBrowser Events

The WebBrowser control notifies its container when something interesting happens by sending the container an event. Events generated by the WebBrowser control are conveyed through the DWebBrowserEvents2 interface. Commonly used events are listed in Table 12.3.

Table 12.3. Commonly Used WebBrowser Events

Event	Description
`A DownloadBegin`	A download is beginning.
`DownloadComplete`	A download has been completed.
`BeforeNavigate2`	Navigation is about to occur, possibly due to reasons other than the `Navigate2` function being called.
`NavigateComplete2`	Navigation has been completed, and at least part of the document has been downloaded.
`DocumentComplete`	The document has been completely loaded.

Additional events can be found in the online documentation or by reading ExDisp.IDL.

An Example Project Using the WebBrowser Control

As an example of how a WebBrowser ActiveX control can be embedded into a dialog box, the CD-ROM that accompanies this book includes WebCtl, a dialog box-based MFC project that uses a WebBrowser ActiveX control in its main dialog box. The WebCtl project navigates to the Microsoft Visual C++ Web page, and allows the user to navigate to any linked page. The WebCtl application also displays the control panel folder, enabling a user to launch control panel applets.

The full WebCtl project can be found on the CD-ROM that accompanies this book.

Adding the WebBrowser ActiveX Control to an MFC Project

The first step in using the WebBrowser ActiveX control in a project is to add it to the Tool Palette that's displayed when editing dialog box resources. After the control has been added to the tool palette, you can drag it on to your dialog box resources just like any other control.

In Chapter 24, you'll see how to take advantage of the components and controls included with Visual C++. Right now, we're only interested in the WebBrowser control.

Select Project, Add to Project, Components and Controls… from the menu. The Components and Controls dialog box will be displayed, as shown in Figure 12.2.

Figure 12.2 The Components and Controls dialog box.

Click on the folder labeled Registered ActiveX Controls. This will display all of the ActiveX controls that are available for your use, as shown in Figure 12.3.

Figure 12.3 The available ActiveX controls are listed in the Components and Controls dialog box.

Click on the icon labeled Microsoft WebBrowser and then click the Insert button. Click the OK button on the confirmation dialog. The type library for the WebBrowser control will be read, and you will be asked to confirm the addition of the CWebBrowser2 class to your project—click OK to add the class to your project, then click the Close button to close the dialog box.

After the WebBrowser control is added to your project, an icon will be added to the Control Palette, as shown in Figure 12.4.

Figure 12.4 The Control Palette with a WebBrowser icon.

After adding the WebBrowser control to the project, it can be placed on a dialog box resource just like any other control. You can use drag and drop, or you can select the control and drag a rectangle on the dialog box. Figure 12.5 shows the main dialog box used by the WebCtl project after adding the WebBrowser control and other controls.

Figure 12.5 The main dialog box used by the WebCtl project.

The controls used in the dialog box are listed in Table 12.4.

Table 12.4. Controls Used in the Main WebCtl Dialog Box

Control	Resource ID
WebBrowser control	`IDC_WEB_BROWSER`
Control Panel button	`IDC_CTL_PANEL`

Use ClassWizard to associate a CWebCtlDlg member variable with the WebBrowser control, using the values from Table 12.5.

Table 12.5. `CWebCtlDlg` Member Variables

Control Variable	Category	Type	Member Variable
`IDC_WEB_BROWSER`	Control	`CWebBrowser2`	`m-wb`

Modify the CWebCtlDlg::OnCtlPanel function as shown in Listing 12.2, which navigates to the special folder location for the Windows Control Panel.

Example 12.2. Navigating to a Special Folder Location Using the WebBrowser Control

void CWebCtlDlg::OnCtlPanel()
{
    LPITEMIDLIST pidl;
    COleVariant  varEmpty;
    COleVariant  varPidl;
    // Retrieve the control panel's folder PIDL
    HRESULT      hr = SHGetSpecialFolderLocation(NULL,
                                                 CSIDL_CONTROLS,
                                                 &pidl);
    if(FAILED(hr))
    {
        AfxMessageBox("ShGetSpecialFolderLocation Failed");
        return;
    }

    // Stuff the PIDL into a VARIANT
    VARIANT      varTemp;
    hr = PidlToVariant(pidl, &varTemp);
    if(SUCCEEDED(hr))
    {
        // Attach the VARIANT to a COleVariant
        varPidl.Attach(varTemp);
        // Go to the special folder location
        m_wb.Navigate2(varPidl,
                       &varEmpty,
                       &varEmpty,
                       &varEmpty,
                       &varEmpty);
    }
    else
    {
        AfxMessageBox("PidlToVariant Failed");
    }
    // Free the PIDL
    CoTaskMemFree(pidl);
    VariantClear(&varPidl);
}

In Listing 12.2, the OnCtlPanel function passes a PIDL to the Navigate2 function in order to display the control panel folder. First, the PIDL is loaded using the SHGetSpecialFolderLocation function. Next, the PidlToVariant helper function is used to stuff the PIDL into a VARIANT; the source code for this function is provided in the next listing.

Next, the VARIANT is attached to an instance of COleVariant, and passed to the Navigate2 member function. Before returning from the function, the PIDL is freed using the CoTaskMemFree function.

Two helper functions are used to stuff the PIDL into a VARIANT. These functions are shown in Listing 12.3. Add the functions to the top of the WebCtlDlg.cpp file, before any CWebCtlDlg functions.

Example 12.3. Helper Functions Used to Manipulate PIDLs.

// Calculate the length of the PIDL. Unfortunately, there isn't
// an API call to do this - you must walk the PIDL to calculate
// the size.
UINT GetPidlLength(LPITEMIDLIST pidl)
{
    ASSERT_POINTER(pidl, ITEMIDLIST);
    UINT cbPidl = sizeof(pidl->mkid.cb);
    while(pidl && pidl->mkid.cb)
    {
        cbPidl += pidl->mkid.cb;
        // Walk to next item
        BYTE* ptr = reinterpret_cast<BYTE*>(pidl);
        ptr += pidl->mkid.cb;
        pidl = reinterpret_cast<LPITEMIDLIST>(ptr);
    }
    ASSERT(cbPidl > 0);
    return cbPidl;
}

HRESULT PidlToVariant(LPITEMIDLIST pidl, LPVARIANT var)
{
    ASSERT_POINTER(pidl, ITEMIDLIST);
    ASSERT_POINTER(var, VARIANT);
    if(!pidl || !var)
        return E_POINTER;

    VariantInit(var);

    UINT cbPidl = GetPidlLength(pidl);
    LPSAFEARRAY psa = SafeArrayCreateVector(VT_UI1, 0, cbPidl);
    if(psa)
    {
        MoveMemory(psa->pvData, pidl, cbPidl);
        var->vt = VT_UI1|VT_ARRAY;
        var->parray = psa;
        return NOERROR;
    }
    return E_OUTOFMEMORY;
}

There are two functions in Listing 12.3. Taken together the GetPidlLength and PidlToVariant functions take a PIDL as input, and copy the PIDL into a SAFEARRAY consisting of an array of bytes. The SAFEARRAY is then copied into a VARIANT.

The GetPidlLength function walks the internal structure of an ITEMIDLIST structure, and determines the size of the structure. As PIDLs can be a list of individual items, the function must calculate the length of each item in the list. The final item in the PIDL will consist of an item with a length of 0.

The PidlToVariant function calls GetPidlLength to determine the size of the PIDL. It then allocates the SAFEARRAY and copies the PIDL into it. The SAFEARRAY is then copied into the VARIANT structure.

Add the contents of Listing 12.4 to the end of the CWebCtl::OnInitDialog function. These lines of code load the Visual C++ Web page at Microsoft.

Example 12.4. Code Added to the `CWebCtl::OnInitDialog` Function

BOOL CWebCtlDlg::OnInitDialog()
    CDialog::OnInitDialog();
    // Existing code omitted
    .
    .
    .
    // TODO: Add extra initialization here
    COleVariant varEmpty;
    m_wb.Navigate("http://msdn.microsoft.com/visualc",
                  &varEmpty,
                  &varEmpty,
                  &varEmpty,
                  &varEmpty);
    return TRUE;
}

Build and run the WebCtl project. When the project runs, the Microsoft Visual C++ page is initially displayed. If you click on the Control Panel button, the Control Panel is displayed.