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.
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( ).
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:
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.