Using the WebBrowser Control from C/C++

This section describes some of the common implementations of the WebBrowser control, including:

Adding Internet Browsing Functionality to Your Application

One of the most common uses for the WebBrowser control is to add Internet browsing functionality to your application. Using the IWebBrowser2 interface, you can browse to any location in the local file system, on the network, or on the World Wide Web. You can use the Navigatemethod to tell the control which location to browse to. The first parameter is a string that contains the name of the location. To browse to a location in the local file system or on the network, specify the full path to the file system location or the Universal Naming Convention (UNC) name of the location on the network. To browse to a site on the World Wide Web, specify the URL of the site. By including a text box in your application, you can let the user specify the location to browse to and then pass the location to the Navigate method.

In this example, the WebBrowser control was inserted into a basic Microsoft Foundation Class Library (MFC) application. A class was added to the project, and the control was dynamically created in the OnCreate handler of the application’s View class.

CRect rect;
GetClientRect (&rect);

// Create the control.
m_pBrowser = new CWebBrowser;
ASSERT (m_pBrowser);
if (!m_pBrowser->Create(NULL,NULL,WS_VISIBLE,rect,this,NULL))
{
    TRACE("failed to create browsern");
    delete m_pBrowser;
    m_pBrowser = NULL;
    return 0;
}

// Initialize the first URL.
COleVariant noArg;
m_pBrowser->Navigate("www.microsoft.com",&noArg,&noArg,&noArg,&noArg);
return 0;

In addition, the Navigate method allows you to target a specific frame on an HTML page, causing the WebBrowser control to display a Web site or file system location in that frame. First, you would call the Navigate method and specify the URL of an HTML page that contains a frame. Then, by specifying the name of the frame in subsequent calls to Navigate, you can direct the control to display subsequent locations within that frame.

You can also use the get_LocationName and get_LocationURL methods to retrieve information about the location that the WebBrowser control is currently displaying. If the location is an HTML page on the World Wide Web, get_LocationName retrieves the title of that page, andget_LocationURL retrieves the URL of that page. If the location is a folder or file on the network or local computer, get_LocationName and get_LocationURL both retrieve the UNC or full path of the folder or file.

Printing Pages with the WebBrowser Control

Although the WebBrowser control does not support a print method, you can print its contents using one of the following methods:

Set the focus to the WebBrowser control and send a key combination of CTRL+P.

Call the get_Document method, which returns an IDispatch pointer. Using this IDispatch pointer, call QueryInterface on IID_IOleCommandTarget. With the object pointer returned, call Exec (NULL, OLECMDID_PRINT, 0, NULL, NULL).

LPDISPATCH lpDispatch = NULL;
LPOLECOMMANDTARGET lpOleCommandTarget = NULL;

lpDispatch = m_pBrowser.get_Document();
ASSERT(lpDispatch);

lpDispatch->QueryInterface(IID_IOleCommandTarget, (void**)&lpOleCommandTarget);
ASSERT(lpOleCommandTarget);

lpDispatch->Release();

// Print contents of WebBrowser control.
lpOleCommandTarget->Exec(NULL, OLECMDID_PRINT, 0, NULL,NULL);
lpOleCommandTarget->Release();

Changing Fonts with the WebBrowser Control

The WebBrowser automation model does not support a method that allows you to change the font of the text of the currently displayed page. However, the WebBrowser control exposes this functionality through the IOleCommandTarget interface. Call the get_Document method, which returns an IDispatch pointer. Using this IDispatch pointer, call QueryInterface on IID_IOleCommandTarget. With this IOleCommandTarget interface pointer, call Exec with OLECMDID_ZOOM and use the pvaIn input argument to pass a value in the range of 0 to 5 (where 0 is smallest) indicating the desired scale of the font. This, in effect, mimics the functionality available through the Internet Explorer Fonts command on the View menu.

LPDISPATCH pDisp = NULL;
LPOLECOMMANDTARGET pCmdTarg = NULL;

pDisp = m_pBrowser.get_Document();
ASSERT(pDisp);

pDisp->QueryInterface(IID_IOleCommandTarget, (LPVOID*)&pCmdTarg);
ASSERT(pCmdTarg);

VARIANT vaZoomFactor;   // input arguments
VariantInit(&vaZoomFactor);
V_VT(&vaZoomFactor) = VT_I4;
V_I4(&vaZoomFactor) = fontSize;

pCmdTarg->Exec(NULL,
		OLECMDID_ZOOM,
		OLECMDEXECOPT_DONTPROMPTUSER,
		&vaZoomFactor,
		NULL);
VariantClear(&vaZoomFactor);

if (pCmdTarg)
   pCmdTarg->Release(); // release document's command target
if (pDisp)
   pDisp->Release();    // release document's dispatch interface

Working with WebBrowser Events

The WebBrowser control fires a number of different events to notify an application of user- and browser-generated activity. The events are implemented using the DWebBrowserEvents2 interface. When the control is about to navigate to a new location, it fires a BeforeNavigate2event that specifies the URL or path of the new location and any other data that will be transmitted to the Internet server through the HTTP transaction. The data can include the HTTP header, HTTP post data, and the URL of the referrer. BeforeNavigate2 also includes a cancel flag that you can set to FALSE to cancel the navigation. The WebBrowser control fires the NavigateComplete2 event after it has navigated to a new location. This event includes the same information as BeforeNavigate2, but NavigateComplete2 does not include the cancel flag.

When the WebBrowser control is about to begin a download operation, it fires the DownloadBegin event. The control fires a number of ProgressChange events as the operation progresses, and then it fires the DownloadComplete event after completing the operation. Applications typically use these three events to indicate the progress of the download operation, often by displaying a progress bar. An application would show the progress bar in response to DownloadBegin, update the progress bar in response to ProgressChange, and hide it in response toDownloadComplete.

When an application calls the Navigate method with the Flags parameter set to navOpenInNewWindow, the WebBrowser control fires the NewWindow2 event before navigating to the new location. The event includes information about the new location and a flag that indicates whether the application or the control is to create the new window. Set this flag to TRUE if your application will create the window or to FALSE if the WebBrowser control should create it.

You will need to implement an event sink to capture and handle the various events. The Internet Client SDK includes a generic event sink class called EVTSINK. For more information, refer to the SamplesBaseCtlObjvw subdirectory within your SDK.

Andrew's Garage