### Using the WebBrowser Control

The WebBrowser control adds browsing, document viewing, and data downloading capabilities to your applications. It allows the user to browse sites on the Internet's World Wide Web, as well as folders in the local file system and on a network. The WebBrowser control supports Web browsing through both point-and-click hyperlinking and Uniform Resource Locator (URL) navigation. Also, the control maintains a history list that allows the user to browse forward and backward through previously browsed sites, folders, and documents.

The WebBrowser control includes support for parsing and displaying HTML-encoded documents. It is also an ActiveX document container that can host any ActiveX document. This means that richly formatted documents, such as a Microsoft Excel spreadsheet or Microsoft Word documents, can be opened and edited in-place from within the WebBrowser control. WebBrowser is also an ActiveX control container that can host any ActiveX control.

### Possible Uses

Some possible uses of the WebBrowser control are:

- To enable the user to navigate to and view HTML documents on the local computer, network, or World Wide Web.
- To provide a single frame in which the user can view and edit all types of ActiveX documents.
- To create a customized Web browsing application based on the WebBrowser control.

### Navigate to a New Location with the Navigate Method

The WebBrowser control can browse to any location in the local file system, on the network, or on the World Wide Web. You use the 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 Universal Naming Convention (UNC) name of the location on the network. To browse to a site on the World Wide Web, specify the URL of the site. 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 Navigate method.

The 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 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 Navigate, you can direct the control to display subsequent locations within that frame.

You can use the LocationName and LocationURL properties to retrieve information about the location that the WebBrowser control is currently displaying. If the location is an HTML page on the World Wide Web, LocationName retrieves the title of that page, and LocationURL retrieves the URL of that page. If the location is a folder or file on the network or local computer, LocationName and LocationURL both retrieve the UNC or full path of the folder or file.

An HTML author can create a hyperlink that causes an Internet server to execute a program whenever the hyperlink is selected. The hyperlink typically passes data to the program during the HTTP transaction, and the program processes the data. The Navigate method supports navigating to such a hyperlink, and includes parameters that allow you to specify data to pass to the program. You can specify an HTTP header, HTTP post data, and the URL of the referring document. The HTTP header specifies such things as the action required of the server, the type of data being passed to the server, or a status code. The HTTP post data is the actual data for the program to process. The referring document is the HTML document that contains the hyperlink.

### Update Cached Pages with the Refresh or Refresh2 Method

The WebBrowser control stores Web pages from recently visited sites in cached memory on the user's hard disk so that, when the control revisits a site, it can save time by reloading the page from the cache rather than downloading it again from the Internet server. You can force the WebBrowser control to re-download a page by using the Refresh or Refresh2 method—this ensures that the user is viewing the current version of the page. Also, you can prevent the control from using the cache by specifying the navNoReadFromCache and navNoWriteToCache flags when calling the Navigate method.

### Navigate the History List with the GoBack and GoForward Methods

During a browsing session, the WebBrowser control maintains a history list of all Web sites that it visited during the session (unless you specify navNoHistory when calling the Navigate method). You can direct the control to browse backward and forward through the sites in the list by using the GoBack and GoForward methods.

You can also use the GoHome method to cause the WebBrowser control to return to the user's home or start page, and the GoSearch method to go to the user's Web searching page.

### Control Browsing Operations with the Busy Property and Stop Method

You can use the Busy property to determine if the WebBrowser control is in the process of navigating to a new location or downloading a file. If the control is busy, you can use the Stop method to cancel the navigation or the download before it is finished.

### Hide or Show the WebBrowser Control with the Visible Property

By default, the WebBrowser control is hidden when it is first created, but it becomes visible after calling the Navigate or GoSearch method. You can also set the Visible property to True to show the control, or to False to hide it.

### WebBrowser Events

The WebBrowser control fires a number of different events to notify an application of user- and browser-generated activity. When the control is about to navigate to a new location, it fires a BeforeNavigate 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. The BeforeNavigate event also includes a cancel flag that you can set to False to cancel the navigation. The WebBrowser control fires the NavigateComplete event after it has navigated to a new location. This event includes the same information as BeforeNavigate, except NavigateComplete does not include the cancel flag.

Whenever the WebBrowser control is about to begin a download operation, it fires the DownloadBegin event. The control fires a number of ProgressChange events as the operation progresses, and then fires the 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 DownloadBegin, update the progress bar in response to ProgressChange, and hide it in response to DownloadComplete.

When an application calls the Navigate method with the navOpenInNewWindow flag, the WebBrowser control fires the NewWindow event before navigating to the new location. The event includes information about the new location, and a flag that indicates whether the application or the control is to create the new window. Set this flag to True if your application will create the window, or to False if the WebBrowser control should create it.

© 1996 Microsoft Corporation