Using the WebBrowser Control from C/C++
This section describes some common implementations of the WebBrowser control in C/C++, including:
- WebBrowser Control Basics
- Adding Internet Browsing Functionality to Your Application
- Printing Pages with the WebBrowser Control
- Changing Text Size with the WebBrowser Control
- Working with WebBrowser Events
WebBrowser Control Basics
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 IWebBrowser2::Navigate method 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 UNC name of the location on the network. To browse to a site on the World Wide Web, specify the URL of the site.
The IWebBrowser2::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 IWebBrowser2::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 IWebBrowser2::Navigate, you can direct the control to display subsequent locations within that frame.
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 IWebBrowser2::Navigate method. You can also retrieve information about the resource that is currently displayed. If the location is an HTML page, IWebBrowser2::get_LocationName retrieves the title of that page, and IWebBrowser2::get_LocationURL retrieves the URL of that page. If the location is a folder or file on the network or local computer, these methods both retrieve the UNC or full path of the folder or file.
Adding Internet Browsing Functionality to Your Application
To add the WebBrowser control to a basic Microsoft Foundation Classes (MFC) application, perform the following steps.
- Right-click the Project name, and point to Add, the select Class... from the context menu.
- Select "MFC Class From ActiveX Control" and click Add.
- Select "Microsoft Web Browser" from among the classes listed in the registry. Highlight the IWebBrowser2 interface, and click the right arrow to generate a new CWebBrowser2 class.
- Click Finish.
With the new class added to the project, you can dynamically create the control in the OnCreate handler of the application's view class. The following code assumes you have added a m_pBrowser member variable to the view.
int CChildView::OnCreate(LPCREATESTRUCT lpCreateStruct) { // Create the control. m_pBrowser = new CWebBrowser2; ASSERT (m_pBrowser); if (!m_pBrowser->Create(NULL, NULL, WS_VISIBLE, CRect(0,0,0,0), this, NULL)) { TRACE("failed to create browser/n"); delete m_pBrowser; m_pBrowser = NULL; return 0; } // Initialize the first URL. COleVariant noArg; CString strURL("www.microsoft.com"); m_pBrowser->Navigate(strURL, &noArg, &noArg, &noArg, &noArg); return 0; }
Finally, move the control to cover the desired area in the OnSize handler. Remember to use a NULL background brush when registering the view window class to prevent screen flicker when the WebBrowser control is resized.
void CChildView::OnSize(UINT nType, int cx, int cy) { m_pBrowser->MoveWindow(0, 0, cx, cy); }
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:
- Send the WebBrowser control a key combination of CTRL+P.
- Retrieve the IOleCommandTarget interface of document, and execute OLECMDID_PRINT, as follows:
LPDISPATCH pDisp = m_pBrowser->get_Document(); if(pDisp) { LPOLECOMMANDTARGET pCmdTarg = NULL; pDisp->QueryInterface(IID_IOleCommandTarget, (void**)&pCmdTarg); if(pCmdTarg) { // Print contents of WebBrowser control. pCmdTarg->Exec(NULL, OLECMDID_PRINT, OLECMDEXECOPT_PROMPTUSER, NULL, NULL); pCmdTarg->Release(); } pDisp->Release(); }
Changing Text Size with the WebBrowser Control
In Internet Explorer, you can increase or decrease the size of the text from the View menu, but the WebBrowser control does not have a method to do this. Instead, the control exposes this functionality through the IOleCommandTarget interface of the document. Call IOleCommandTarget::Exec with OLECMDID_ZOOM and pass a value in the range of 0 to 4 (where 0 is smallest) to indicate the desired scale of the font.
LPDISPATCH pDisp = m_pBrowser->get_Document(); if(pDisp) { LPOLECOMMANDTARGET pCmdTarg = NULL; pDisp->QueryInterface(IID_IOleCommandTarget, (void**)&pCmdTarg); if(pCmdTarg) { COleVariant vaZoomFactor; // input argument V_VT(&vaZoomFactor) = VT_I4; V_I4(&vaZoomFactor) = fontSize; // 0 - 4 // Change the text size. pCmdTarg->Exec(NULL, OLECMDID_ZOOM, OLECMDEXECOPT_DONTPROMPTUSER, &vaZoomFactor, NULL); pCmdTarg->Release(); } pDisp->Release(); }
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 DWebBrowserEvents2::BeforeNavigate2 event 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. DWebBrowserEvents2::BeforeNavigate2 also includes a Cancel flag that you can set to FALSE to cancel the navigation. The WebBrowser control fires the DWebBrowserEvents2::NavigateComplete2 event after it has navigated to a new location. This event includes the same information as DWebBrowserEvents2::BeforeNavigate2, but DWebBrowserEvents2::NavigateComplete2 does not include the Cancel flag.
When the WebBrowser control is about to begin a download operation, it fires the DWebBrowserEvents2::DownloadBegin event. The control fires a number of DWebBrowserEvents2::ProgressChange events as the operation progresses, and then it fires the DWebBrowserEvents2::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 DWebBrowserEvents2::DownloadBegin, update the progress bar in response to DWebBrowserEvents2::ProgressChange, and hide it in response to DWebBrowserEvents2::DownloadComplete.
When an application calls the IWebBrowser2::Navigate method with the Flags parameter set to navOpenInNewWindow, the WebBrowser control fires the DWebBrowserEvents2::NewWindow2 event before navigating to the new location. The event also includes a Cancel flag and a pointer that can receive a new browser window, if you prefer to create one of your own. If not, the event fires as normal, and opens a new InternetExplorer object to handle the navigation.