Section 3.4. Put the Web in a Window

3.4. Put the Web in a Window

There's no shortage of reasons why you might want to integrate a web page window into your application. Maybe you want to show your company web site, create a customized browser, or display HTML product documentation. In .NET 1.0 and .NET 1.1, you could use a web browser window through COM interop, but there were a number of quirky or missing features. The new WebBrowser control in .NET 2.0 addresses these issues with easy web integration, support for printing and saving documents, and the ability to stop a user from navigating to the wrong web site.

---

Note: . NET's new managed WebBrowser control lets you show an HTML page or allow a user to browse a web site from inside your Windows applicationwith no interop headaches.

---

3.4.1. How do I do that?

The System.Windows.Forms.WebBrowser control wraps an Internet Explorer window. You can drop the WebBrowser control onto any Windows form straight from the Visual Studio .NET toolbox.

To direct the WebBrowser to show a page, you simply set the Url property to the target web page. All navigation in the WebBrowser is asynchronous, which means your code continues running while the page is downloading. To check if the page is complete, verify that the ReadyState property is Completed or, better yet, react to a WebBrowser event.

---

Note: The WebBrowser control supports everything IE does, including JavaScript, ActiveX controls, and plug-ins.

---

The WebBrowser events unfold in this order:

---

Note: WebBrowser provides methods that duplicate the browser functions every web surfer is familiar with, such as Stop( ), Refresh( ), GoBack( ), GoForward( ), GoHome( ), GoSearch( ), Print( ), ShowPrintDialog( ), and ShowSave-AsDialog( ).

---

1. Navigating fires when you set a new Url or the user clicks a link. This is your chance to cancel the navigation before anything happens.

2. Navigated fires after Navigating, just before the web browser begins downloading the page.

3. The ProgressChanged event fires periodically during a download and gives you information about how many bytes have been downloaded and how many are expected in total.

4. DocumentCompleted fires when the page is completely loaded. This is your chance to process the page.

Example 3-3 shows the event-handling code for a form, WebForm, which hosts a WebBrowser along with a simple status bar and progress bar. The WebBrowser displays a local HTML file (note how the URL starts with file:///, not http://) and ensures that any external web links are opened in standalone Internet Explorer windows.

Example 3-3. Building a basic browser window

Public Class WebForm          Private Sub WebForm_Load(ByVal sender As Object, ByVal e As EventArgs) _       Handles MyBase.Load         ' Prevent the user from dragging and dropping links onto this browser.         Browser.AllowWebBrowserDrop = False              ' Go to the local documentation page.         Browser.Url = new Uri("file:///" & _           My.Application.StartupPath & "\Doc.html")     End Sub          Private Sub Browser_Navigating(ByVal sender As Object, _       ByVal e As WebBrowserNavigatingEventArgs) Handles Browser.Navigating         If Not e.Url.IsFile Then             ' Don't resolve this external link.             ' Instead, use the Navigate( ) method to open a             ' standalone IE window.             e.Cancel = True             Browser.Navigate(e.Url, True)         End If     End Sub          Private Sub Browser_Navigated(ByVal sender As Object, _       ByVal e As WebBrowserNavigatedEventArgs) Handles Browser.Navigated         ' Show the progress bar.         Progress.Visible = True     End Sub          Private Sub Browser_ProgressChanged(ByVal sender As Object, _       ByVal e As WebBrowserProgressChangedEventArgs) _       Handles Browser.ProgressChanged         ' Update the progress bar.         Progress.Maximum = e.MaximumProgress         Progress.Value = e.CurrentProgress     End Sub          Private Sub Browser_DocumentCompleted(ByVal sender As Object, _       ByVal e As WebBrowserDocumentCompletedEventArgs) _       Handles Browser.DocumentCompleted         ' Hide the progress bar.         Progress.Visible = False     End Sub          Private Sub Browser_StatusTextChanged(ByVal sender As Object, _       ByVal e As EventArgs) Handles Browser.StatusTextChanged         ' Display the text that IE would ordinarily show         ' in the status bar.         Status.Text = Browser.StatusText     End Sub      End Class

Figure 3-6 shows the form with its customized WebBrowser window. The window also includes a StatusStrip to display status text and a progress indicator when pages are being loaded.

Figure 3-6. An embedded web window

---

Note: The WebBrowser window is stripped to the bare minimum and doesn't include a toolbar, address bar, or status bar (although you can add other controls to your form).

---

3.4.2. What about...

...other web surfing tricks? WebBrowser gives you almost all of the power of IE to use in your own applications. Here are a few more tricks you might want to try:

• Instead of setting the Url property, call the Navigate( ) method, which has two useful overloads. The first (shown in the previous example), allows you to launch a standalone browser window. The second allows you to load a document into a specific frame in the current page.

• Instead of using URLs, you can load an HTML document directly from another resource, using the DocumentStream or DocumentText property. The DocumentStream accepts a reference to any Stream object, while the DocumentText property accepts a string that contains the HTML data.

• Once you've loaded a document, you can explore it using the HTML document model that's built into .NET. The jumping-off point is the Document property, which returns an HtmlDocument object that models the current document, including its tags and content.

• You can direct the WebBrowser to a directory to give the user quick-and-dirty file browsing abilities. Keep in mind, however, that you won't be able to prevent them from copying, moving, or deleting files!

3.4.3. Where can I learn more?

For the full set of properties, look up the System.Windows.Forms.WebBrowser class in the MSDN class library reference.