Section 23.9. WebBrowser Class

23.9. WebBrowser Class

With FCL 2.0, Microsoft introduced the WebBrowser class (namespace System.Windows.Forms), which enables applications to incorporate Web browsing capabilities. The control provides methods for navigating Web pages and maintains its own history of Web sites visited. It also generates events as the user interacts with the content displayed in the control so that your application can respond to events such as the user clicking the links displayed in the content.

Figure 23.8 demonstrates the WebBrowser class's capabilities. Class FrmBrowser provides the basic functionality of a Web browser, allowing the user to navigate to a URL, move backward and forward through the history of visited sites, and reload the current Web page.

Figure 23.8. WebBrowser class example.

  1  ' Fig. 23.8: FrmBrowser.vb  2  ' WebBrowser class example.  3  4  Public Class FrmBrowser  5     ' navigate back one page  6     Private Sub btnBack_Click(ByVal sender As System.Object, _  7        ByVal e As System.EventArgs) Handles btnBack.Click  8  9        webBrowser.GoBack() 10     End Sub ' btnBack_Click 11 12     ' navigate forward one page 13     Private Sub btnForward_Click(ByVal sender As System.Object, _ 14        ByVal e As System.EventArgs) Handles btnForward.Click 15 16        webBrowser.GoForward() 17     End Sub ' btnForward_Click 18 19     ' stop loading the current page 20     Private Sub btnStop_Click(ByVal sender As System.Object, _ 21        ByVal e As System.EventArgs) Handles btnStop.Click 22 23        webBrowser.Stop() 24     End Sub ' btnStop_Click 25 26     ' reload the current page 27     Private Sub btnReload_Click(ByVal sender As System.Object, _ 28        ByVal e As System.EventArgs) Handles btnReload.Click 29 30        webBrowser.Refresh() 31     End Sub ' btnReload_Click 32 33     ' navigate to the user's home page 34     Private Sub btnHome_Click(ByVal sender As System.Object, _ 35        ByVal e As System.EventArgs) Handles btnHome.Click 36 37        webBrowser.GoHome() 38     End Sub ' btnHome_Click 39 40     ' if the user pressed enter, navigate to the specified URL 41     Private Sub txtNavigation_KeyDown(ByVal sender As System.Object, _ 42        ByVal e As System.Windows.Forms.KeyEventArgs) _ 43        Handles txtNavigation.KeyDown 44 45        If e.KeyCode = Keys.Enter Then 46           webBrowser.Navigate(txtNavigation.Text) 47        End If 48     End Sub ' txtNavigation_KeyDown 49 50     ' enable btnStop while the current page is loading 51     Private Sub webBrowser_Navigating(ByVal sender As System.Object, _ 52        ByVal e As System.Windows.Forms.WebBrowserNavigatingEventArgs) _ 53        Handles webBrowser.Navigating 54 55        btnStop.Enabled = True 56     End Sub' webBrowser_Navigating 57 58     ' update the status text 59     Private Sub webBrowser_StatusTextChanged( _ 60        ByVal sender As System.Object, ByVal e As System.EventArgs) _ 61        Handles webBrowser.StatusTextChanged 62 63        txtStatus.Text = webBrowser.StatusText 64     End Sub ' webBrowser_StatusTextChanged 65 66     ' update the ProgressBar for how much of the page has been loaded 67     Private Sub webBrowser_ProgressChanged( _ 68        ByVal sender As System.Object, ByVal e As _ 69        System.Windows.Forms.WebBrowserProgressChangedEventArgs) _ 70        Handles webBrowser.ProgressChanged 71        ' Check if e.MaximumProgress is 0 or 72        ' if e.MaximumProgress is less than e.CurrentProgress 73        If e.MaximumProgress <> 0 And _ 74           e.MaximumProgress >= e.CurrentProgress Then 75 76           prgPage.Value = Convert.ToInt32( _              77              100 * e.CurrentProgress / e.MaximumProgress) 78        End If 79     End Sub ' webBrowser_ProgressChanged 80 81     ' update the web browser's controls appropriately 82     Private Sub webBrowser_DocumentCompleted( _ 83        ByVal sender As System.Object, ByVal e As _ 84        System.Windows.Forms.WebBrowserDocumentCompletedEventArgs) _ 85        Handles webBrowser.DocumentCompleted 86        ' set the text in txtNavigation to the current page's URL 87        txtNavigation.Text = webBrowser.Url.ToString()            88 89        ' enable or disable btnBack and btnForward   90        btnBack.Enabled = webBrowser.CanGoBack       91        btnForward.Enabled = webBrowser.CanGoForward 92 93        ' disable btnStop       94        btnStop.Enabled = False 95 96        ' clear the prgPage 97        prgPage.Value = 0   98     End Sub ' webBrowser_DocumentCompleted 99 100    ' update the title of the Browser 101    Private Sub webBrowser_DocumentTitleChanged( _ 102       ByVal sender As System.Object, ByVal e As System.EventArgs) _ 103       Handles webBrowser.DocumentTitleChanged 104 105       Me.Text = webBrowser.DocumentTitle & " - Browser" 106    End Sub ' webBrowser_DocumentTitleChanged 107  End Class ' FrmBrowser 

Lines 638 define five Click event handlers, one for each of the five navigation Buttons that appear at the top of the Form. Each event handler calls a corresponding Web-Browser method. WebBrowser method GoBack (line 9) navigates back to the previous page in the navigation history. Method GoForward (line 16) navigates forward to the next page in the navigation history. Method Stop (line 23) stops loading the current page. Method Refresh (line 30) reloads the current page. Method GoHome (line 37) navigates to the user's home page, as defined under Internet Explorer's settings (under Tools > Internet Options... in the Home page section).

The TextBox to the right of the navigation buttons allows the user to enter the URL of a Web site to browse. When the user types each keystroke in the TextBox, the event handler in lines 4148 executes. If the key pressed was Enter, line 46 calls WebBrowser method Navigate to retrieve the document at the specified URL.

A WebBrowser object generates a Navigating event when it starts loading a new page. When this occurs, the event handler in lines 5156 executes, and line 55 enables btnStop so that the user can cancel the loading of the Web page.

Typically, a user can see the status of a loading Web page at the bottom of the browser window. For this reason, we include a TextBox control (named txtStatus) and a ProgressBar control (named prgPage) at the bottom of our Form. A WebBrowser object generates a StatusTextChanged event when its StatusText property changes. The event handler for this event (lines 5964) assigns the new contents of the WebBrowser's Status Text property to txtStatus's Text property (line 63) so that the user can monitor the WebBrowser's status messages. A WebBrowser object generates a ProgressChanged event when its page-loading progress is updated. The ProgressChanged event handler (lines 6779) updates prgPage's Value (lines 7677) to reflect how much of the current document has been loaded.

When the WebBrowser finishes loading a document, it generates a DocumentCompleted event. This executes the event handler in lines 8298. Line 87 updates the contents of txtNavigation so that it shows the URL of the currently loaded page (WebBrowser property Url). This is particularly important if the user browses to another Web page by clicking a link in the existing page. Lines 9091 use properties CanGoBack and CanGoForward to determine whether the back and forward buttons should be enabled or disabled. Since the document is now loaded, line 94 disables btnStop. Line 97 sets prgPage's Value to 0 to indicate that no content is currently being loaded.

Lines 101106 define an event handler for the DocumentTitleChanged event, which occurs when a new document is loaded in the WebBrowser. Line 105 sets FrmBrowser's Text property (which is displayed in the Form's title bar) to the WebBrowser's current DocumentTitle.