WebBrowser Control

With FCL 2.0, Microsoft introduced the WebBrowser control, 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 your application can respond to events such as the user clicking the links displayed in the content.

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

Figure 23.8. WebBrowser control example.

 1 // Fig. 23.8: Browser.cs
 2 // WebBrowser control example.
 3 using System;
 4 using System.Windows.Forms;
 5
 6 public partial class BrowserForm : Form
 7 {
 8 public BrowserForm()
 9 {
10 InitializeComponent();
11 } // end constructor
12
13 // navigate back one page
14 private void backButton_Click( object sender, EventArgs e )
15 {

16 webBrowser.GoBack(); 17 } // end method backButton_Click 18 19 // navigate forward one page 20 private void forwardButton_Click( object sender, EventArgs e ) 21 { 22 webBrowser.GoForward(); 23 } // end method forwardButton_Click 24 25 // stop loading the current page 26 private void stopButton_Click( object sender, EventArgs e ) 27 { 28 webBrowser.Stop(); 29 } // end method stopButton_Click 30 31 // reload the current page 32 private void reloadButton_Click( object sender, EventArgs e ) 33 { 34 webBrowser.Refresh(); 35 } // end method reloadButton_Click 36 37 // navigate to the user's home page 38 private void homeButton_Click( object sender, EventArgs e ) 39 { 40 webBrowser.GoHome(); 41 } // end method homeButton_Click 42 43 // if the user pressed enter, navigate to the specified URL 44 private void navigationTextBox_KeyDown( object sender, 45 KeyEventArgs e ) 46 { 47 if ( e.KeyCode == Keys.Enter ) 48 webBrowser.Navigate( navigationTextBox.Text ); 49 } // end method navigationTextBox_KeyDown 50 51 // enable stopButton while the current page is loading 52 private void webBrowser_Navigating( object sender, 53 WebBrowserNavigatingEventArgs e ) 54 { 55 stopButton.Enabled = true; 56 } // end method webBrowser_Navigating 57 58 // update the status text 59 private void webBrowser_StatusTextChanged( object sender, 60 EventArgs e ) 61 { 62 statusTextBox.Text = webBrowser.StatusText; 63 } // end method webBrowser_StatusTextChanged 64 65 // update the ProgressBar for how much of the page has been loaded 66 private void webBrowser_ProgressChanged( object sender, 67 WebBrowserProgressChangedEventArgs e ) 68 { 69 pageProgressBar.Value = 70 ( int ) ( ( 100 * e.CurrentProgress ) / e.MaximumProgress ); 71 } // end method webBrowser_ProgressChanged 72 73 // update the web browser's controls appropriately 74 private void webBrowser_DocumentCompleted( object sender, 75 WebBrowserDocumentCompletedEventArgs e ) 76 { 77 // set the text in navigationTextBox to the current page's URL 78 navigationTextBox.Text = webBrowser.Url.ToString(); 79 80 // enable or disable backButton and forwardButton 81 backButton.Enabled = webBrowser.CanGoBack; 82 forwardButton.Enabled = webBrowser.CanGoForward; 83 84 // disable stopButton 85 stopButton.Enabled = false; 86 87 // clear the pageProgressBar 88 pageProgressBar.Value = 0; 89 } // end method webBrowser_DocumentCompleted 90 91 // update the title of the Browser 92 private void webBrowser_DocumentTitleChanged( object sender, 93 EventArgs e ) 94 { 95 this.Text = webBrowser.DocumentTitle + " - Browser"; 96 } // end method webBrowser_DocumentTitleChanged 97 } // end class BrowserForm

Lines 1441 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 WebBrowser method. WebBrowser method GoBack (line 16) causes the control to navigate back to the previous page in the navigation history. Method GoForward (line 22) causes the control to navigate forward to the next page in the navigation history. Method Stop (line 28) causes the control to stop loading the current page. Method Refresh (line 34) causes the control to reload the current page. Method GoHome (line 40) causes the control to navigate 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 at lines 4449 executes. If the key pressed was Enter, line 48 calls WebBrowser method Navigate to retrieve the document at the specified URL.

The WebBrowser control generates a Navigating event when the WebBrowser starts loading a new page. When this occurs, the event handler at lines 5256 executes, and line 55 enables stopButton 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 statusTextBox) and a ProgressBar control (named pageProgressBar) at the bottom of our Form. The WebBrowser control generates a StatusTextChanged event when the WebBrowser's StatusText property changes. The event handler for this event (lines 5963) assigns the new contents of the control's StatusText property to statusTextBox's Text property (line 62), so the user can monitor the WebBrowser's status messages. The control generates a ProgressChanged event when the WebBrowser control's page-loading progress is updated. The ProgressChanged event handler (lines 6671) updates pageProgressBar's Value (lines 6970) to reflect how much of the current document has been loaded.

When the WebBrowser finishes loading a document, the control generates a DocumentCompleted event. This executes the event handler at lines 7489. Line 78 updates the contents of navigationTextBox 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 8182 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 85 disables stopButton. Line 88 sets pageProgressBar's Value to 0 to indicate that no content is currently being loaded.

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