Previous Page TOC Next Page See Page



— 4
Using Custom Controls for WWW Programming


If the concept of spending hours pouring over proposed standards, working Internet drafts, and trying to adhere to the HTTP protocol specification aren't your ideas of a good time, but you still want to use the resources of the World Wide Web in your Visual Basic application, help is now available. Since version 1.0 of Visual Basic, custom controls have been available for databases, and with the advent of OLE objects and Visual Basic 4.0, easy-to-use custom controls for the Web are here.

In this chapter I'll go over the functionality of each tool, and give some examples of their uses.

Sax Webster Control


When I began searching for HTML-compatible browser controls, the first one I found was the Webster control. Originally written by an independent developer, the Webster control has since been bought and enhanced by Sax Software. A demo version of the control can be found at their Web site (http://www.saxsoft.com).

http://www.saxsoft.com

The Sax Webster control abstracts away the HTTP protocol, leaving the programmer with enough properties, events, and methods to incorporate a web browser into an application. For example, to set the browser's default home page, change the value of the HomePage property to the desired URL. To load a specific URL, change the value of the PageURL property to the URL. The loading and displaying of the page are taken care of by the Webster control.

The Webster manual claims that the control is a complete WWW browser in a single custom control. After I installed the software, I started a new project in Visual Basic, added the custom control to the toolbox, and dragged the Webster control onto the form. When I ran the application and clicked the Webster control's Home Page (House) icon, up came Sax's WWW page in the browser window, as shown in Figure 4.1. As advertised, a complete Web browser in a single control!

Figure 4.1. The Sax Webster Browser displaying the Sax home page.

The fun begins when you modify the values of the Webster control. By adding a status bar, a button bar, a few text and combo boxes, a proficient programmer can produce a full-featured browser with a minimal of coding effort.

The applications for this tool are as limitless as the World Wide Web itself. These are a few examples: up-to-date online help via your companies Web site, Intranet access using a custom browser, or offline reading of HTML files. This section provides an overview of the properties, methods, and events available with the Webster control and then develops a custom browser using the control.

Webster Properties, Methods, and Events


The following are some properties and methods essential to the Webster control and its function. Only the major properties, methods, and events are covered here. In addition to these properties, methods, and events are most of the standard Visual Basic control properties, as well as properties to control the fonts of the headings, URLs, menus, and so on. The help file provided with the Webster control gives a complete listing of the properties, methods, and events.

PageURL Property

Assigning a new value to this string property is equivalent to entering a URL in a browser's GoTo window and hitting enter. Webster will search for the URL and try to load it. The control will display either the web page (if located) or an appropriate error code if the URL could not be loaded.

HomePage Property

The HomePage property is a string that sets the URL that is loaded when the user clicks on the House icon of the Webster control's default toolbar. The default is http://www.saxsoft.com (The Sax home page).

DownloadDir Property

The DownloadDir property specifies a valid path name where files will be placed when the user elects to save them locally. It can be specified by users when they save a file, or it can be set by the program.

AuthenticName and AuthenticPassword Properties

Some sites require a basic user name/password combination to gain access. The AuthenticName and AuthenticPassword properties can be set for that authentication process.

BrowserName Property

The BrowserName property sets the string that will be placed in the HTTP request message's User-Agent field whenever the Webster control accesses a Web resource. As noted in Chapter 2, "HTTP: How To Speak On The Web," this field identifies the browser to the HTTP server. It can be used for logging purposes or for providing Web site customization based on the browser that is being used to access the Web site.

Enabled Property

This property is similar to the standard Visual Basic Enabled property. When Enabled is set to false, the Webster control does not respond to user-driven events, such as clicking on the toolbar.

IgnoreBaseInFile Property

Setting the IgnoreBaseInFile to False instructs the browser to ignore the <BASE> tags in HTML files. The <BASE> tag provides relative path resolution for links within an HTML file that use relative paths. If your server is named www.myserver.com and you have a link coded as <A HREF="/path1/document.htm"> this would normally generate a URL of http://www.myserver.com/path1/document.htm. By specifying a <BASE> tag somewhere within the HTML file that contains this link, you can modify the URL that is generated. For example, if you have, in the same document as the above <A HREF> tag, a <BASE="/foo">, the URL generated would be http://www.myserver.com/foo/path1/document.htm (note the addition of /foo to the URL).

The IgnoreBaseInFile property, then, allows the user to copy an entire Web site to disk and browse the site locally without worry of a <BASE> tag referring to a URL on the Internet.

FromName Property

The FromName property corresponds to the HTTP From field. The From request message field, as defined in the HTTP specification, provides the e-mail address of the person using the Web browser. It is another logging mechanism similar to the User Agent field but is rarely used due to privacy concerns.

ImageCacheKB Property

This sets the amount of memory the application can use for storing inline images. The larger the number is, the more memory your application takes, but the user viewing a cached page does not have to wait for the images to be retrieved from the remote site.

LoadImages Property

The LoadImages Boolean value determines whether the Webster control automatically loads inline images embedded within the Web pages it's loading.

LoadStatus Property

The LoadStatus property is a read-only property which provides the current status of the browser. The possible values are shown in Table 4.1.

Table 4.1. The possible values of LoadStatus.


Setting

Description

0

Page load is complete

1

Connecting to host

2

Connected, waiting.

3

Page text is loading.

4

Images are loading.

5

Load failure.

6

Unknown—URL failed to load



MaxPageLoads Property

The value of the MaxPageLoads property determines the number of concurrent HTTP requests that can take place at one time.

MaxSockets Property

The setting in MaxSockets determines the maximum number of active TCP/IP sockets the Webster control can use. The term socket refers simply to a single specific connection between two computers on the network that are using a network service.

PageTitle Property

PageTitle returns the HTML title of the current page.

PagesToCache Property

The PagesToCache setting determines how many previously visited pages to hold in memory. The greater the number set here, the more memory the browser uses; however having pages cached reduces load time if the user goes back to pages previously loaded.

ProxyPortHTTP and ProxyServerHTTP Properties

The ProxyPortHTTP and ProxyServerHTTP properties determine the proxy port and proxy server names.

ShowRefer Property

The ShowRefer Boolean property determines whether the HTTP Referer request header field introduced in Chapter 2 is sent to the server when a document is retrieved. The Referer field specifies the URI of the resource from which the request message was generated. For example, if you are on a Web page who's URL is http://www.myserver.com and you click a hyperlink to another Web page, the Referer field sent within the message requesting the page you clicked on will contain the string http://www.myserver.com. When this property is set to False, the Webster control will not use the Referer field in its request messages.

TitleWindowStyle Property

You determine the look of the title window by the settings in TitleWindowStyle. Table 4.2 lists the valid settings and their descriptions.

Table 4.2. Values for the TitleWindowStyle property.


Setting

Description

0

Does not display the title window.

1

Displays the title window at the Top of the control (default).

2

Displays the title window at the bottom of the control.



UrlWindowStyle Property

The UrlWindowStyle setting determines the visibility and location of the current URL window using the values shown in table 4.3.

Table 4.3. Values for the UrlWindowStyle property.


Setting

Description

0

The URL is not displayed.

1

Displays the URL window at the top of the control.

2

Displays the URL window at the bottom of the control (default).



DoClickURL Event

The DoClickURL event is fired every time the user clicks on a hyperlink. The parameters are

Cancel (Boolean)—If set to true, the link will not load. Setting Cancel to true is good for limiting access to certain URLs.


DoLoadImage Event

DoLoadImage indicates to the Webster control's container that an image is about to be loaded. The parameters are

Cancel (Boolean)—If this value is set to true, the image will not be loaded.


HyperlinkTransition Event

The HyperlinkTransition event fires a link when the mouse pointer is moved over a hyperlink. A potential use for this is updating a status bar with the URL of the link that would be loaded if the user clicked on the hypertext. The parameters provided to the event are

IsOverLink (Boolean)—If True, the mouse pointer is directly over the hyperlink. Otherwise, the pointer has moved off of the hyperlink.


LoadComplete Event

The LoadComplete event is fired when the requested Web page text has been completely loaded or when the load request fails. The parameters are the URL of the loaded page as a string, and an integer that indicates the status of the page. The values and their meanings are the same as the LoadStatus property discussed earlier in this section.

AboutBox Method

Calling the AboutBox method displays the Sax Webster About box.

Cancel Method

Cancel stops the loading of the current page.

DismissPage Method

DismissPage removes a specified page from the memory cache.



Any method that accepts a page's URL as a parameter will accept either the URL to any page contained within the Webster page cache or an empty string to signify the currently loaded page.


GetContent Method

The GetContent method returns raw data from either the currently loaded page or from a page within the cache. You specify the byte offset within the page to begin and the number of bytes to return.

GetContentSize Method

This method returns the size in bytes for a document, as specified by the Content Size HTTP header field. If the Content Size HTTP header field is not present, returns 0.

GetContentSizeRead Method

The GetContentSizeRead method returns the number of bytes that have currently been for a document. This is useful while a document is being loaded to determine load status.

GetContentType Method

The GetContentType method returns the Content Type HTTP header field for a document.

GetHiddenFlag, SetHiddenFlag Methods

The GetHiddenFlag method returns a Boolean which indicates whether or not the page specified as a parameter to the method is currently hidden or visible. The SetHiddenFlag method is used to set a specific page to be either hidden or visible.

GetLinkCount, GetLinkURL Methods

The GetLinkCount method returns a count of the URLs contained on the page specified as a parameter to the method. The GetLinkURL returns the URL of the link specified by the method's Index parameter. For example, to add all of the current page's links to a list box, use the following code:

For I% = 0 to Webster1.GetLinkCount("")
    List1.AddItem Webster1.GetLinkURL("", I%)
Next

GetRedirectedURL Method

This method returns the translated URL in cases where HTTP redirections have taken place.

GetStatus Method

The GetStatus method returns a status code for the specified URL. For the possible values returned, see the LoadStatus property discussed earlier.

GetText, GetTextSize Methods

The GetText and GetTextSize methods return the pure text and the byte count for the pure text for a specified page. Note that HTML tags and hyperlinks are not considered text as far as these methods are concerned.

GetTitle Method

Returns the page title for the specified page. The page is what is specified within the <TITLE> tags in the HTML file.

GoHome Method

The GoHome method causes Webster to load the page specified by the HomePage property.

LoadPage Method

The LoadPage method causes Webster to load a specified page. The method also has a Hidden parameter where you instruct Webster on whether or not the page should be hidden or visible after it is loaded (see the GetHiddenFlag and SetHiddenFlag methods discussed earlier for more details).

PageBack, PageForth Methods

These methods instruct Webster to load either the previous or the next page in the control's history list.

Refresh Method

The Refresh method repaints the control, but does not reload the current document from its Web server.

Reload Method

The Reload method reloads the current page from the Web server.

SaveToDisk Method

This method saves the current page to the directory specified by the SaveDir property.

ShowDir Method

The ShowDir method displays the directory page, which allows the user to select and display an HTML file that has been saved to disk.

ShowHistory Method

This method displays the history page, which contains a log of all the URLs the user has loaded during the current session.

ShowStatus Method

The ShowStatus method displays the status page, which displays the status for the currently loaded page.

Coding A Simple Application With the Webster Control


This section discusses the creation of a simple Web browser using the Sax Webster control. Although the Webster control can operate as a good Web browser by itself, you'll want to add some of the functionality present in the commercially available browsers.

This simple application allows you to enter a URL directly into a text box. The Webster control is then used to load the Web page pointed to by the URL. Further, you can store the URL in a bookmark database and retrieve it later using a dropdown combo box on the form. To accomplish these tasks, the following controls are used:


Designing the Form


To get all this done, you need to add a data control, a data-bound combo box that holds the title of the page that you want to load, a textbox for the URL, and a Button to add the current page to the Access database that's used to store the URLs of sites you've visited. You also need a status bar control to give the user feedback about hyperlinks and the status of the Webster control.

Let's start by looking at the layout of the form with the Webster control and the additional controls. Figure 4.2 shows the form in the Visual Basic's design mode.

Figure 4.2. Design mode view of the custom browser.

One important form-level action your code must perform is that on a resize of the client window the Webster control should be resized as well. This means moving the Webster control, as well as the support controls around it, as shown in Listing 4.1.

Listing 4.1. The Form_Resize Event

    'make room for the added controls
    Webster1.Top = 840
    Webster1.Left = 0
    'make room for status bar
    Webster1.Width = ScaleWidth
    If ScaleHeight > 490 Then
        Webster1.Height = ScaleHeight - 490
    End If

By setting the Top property of the Webster object to 840, you give yourself room for the additional controls you add to the top of the form. If the new height is greater than 490 twips, you assign the ScaleHeight—490 value to the Height property of the Webster control to make room for the status bar. If the new height is less than 490, and you subtract 490, this results in a negative number, which is invalid for the Height property of any control.

Setting the Initial Properties of the Webster Control


One property you may want to set at form level or in design mode is the URL of the home page. The home page is the URL loaded when the user clicks on the small House icon in the toolbar. To do this, you add to the Form Load routine. The default home page is Sax Software's home page.

At this point, you could also specify the settings for the fonts used within the browser window, as well as any other tasks that need to be done at application startup, such as whether you wish to provide all of the toolbar buttons Webster makes available.

Setting Up the Access Database


For this limited sample application you will use a single table, two field Access database. The database name is tblUrl, the fields are urlTitle and urlAddress. The urlTitle and urlAddress fields are text, 50 characters long. The urlTitle field holds the user-supplied title of the page; the urlAddress holds the URL of the page.

Front-Ending the Access Database


This section describes how to set up the controls that interact with the database. You need to set the properties of the data control and the data-bound combo box. This is done by setting the properties of the controls as follows:

  1. Set the properties for Data1 — the single data control object you use by selecting the control on the form.

  2. Set the DatabaseName property to the path of the Access database created earlier. The path could be stored and retrieved from the Windows registry if you wanted to get real fancy. However, in this example, set it at design time to a local .MDB file on the hard drive.

  3. Set the DataSource property should be set to tblUrl.

  4. Set the Visible property to False—You don't need user interaction with the data control, so you make it invisible.

  5. Select DBCombo1—The data-bound combo box that holds the title of the page the user wants to access.

  6. Give the control a more descriptive name, such as cboTitle.

  7. Set the control's DataSource and RowSource properties to Data1 and set the DataField, ListField, and BoundColumn properties to urlTitle (the name of the field that holds the user-entered titles).

  8. Select the text box. Give it a more informative name, such as txtURL.

You also add the following code to the data control's Validate event:

Save=False

This prevents the dynaset from being overwritten when new records are selected with the combo box. However, it also makes it impossible to add records using the Update method. You will see how to get around this when you write the code for the Add Favorite button.

Using the StatusBar Control


In this example, you use the simple text flavor of the Visual Basic 4.0 StatusBar Control. By dragging the control onto the form, setting the Style property to 1 (single panel, simple text), you get a very basic, one-panel status bar. You change the text of the panel by setting its SimpleText property in the events of the Webster control (see Listing 4.2):

Listing 4.2. Webster event procedure code.

Private Sub Webster1_DoClickURL(SelectedURL As String, Cancel As Boolean)
    StatusBar1.SimpleText = "Loading " & SelectedURL
End Sub
Private Sub Webster1_HyperlinkTransition(URL As String, ByVal IsOverLink As Boolean)
    StatusBar1.SimpleText = URL
 End Sub
Private Sub Webster1_LoadComplete(URL As String, ByVal Status As Integer)
    StatusBar1.SimpleText = URL & " Loaded."
End Sub

This gives users some much-needed feedback as they use the Webster control: Moving over a hypertext link causes the status bar to display that hyperlink's URL, and the user is also notified when loading is in process and when the page text is completely loaded.

Programming the Data-Bound Combo Box

On the Click event, you want two things to happen: The first is setting the Bookmark property of the data control's Recordset object equal to the value returned by the combo box's SelectedItem property.

The second is to set the PageURL property of the Webster control equal to the URL contained in the database for the item chosen by cboTitle. The code in Listing 4.3 demonstrates how these are accomplished.

Listing 4.3 Code for the cboTitle_Click event.

Private Sub cboTitle_Click(Area As Integer)
    
    If Area = dbcAreaList Then
        If Not (IsEmpty(cboTitle.SelectedItem)) Then
            Data1.Recordset.Bookmark = cboTitle.SelectedItem
            Webster1.PageURL = Data1.Recordset!urlAddress
        End If
    End If
    
End Sub

Note the two If...Then statements at the beginning of the procedure. The first checks to make sure the user has clicked within the list area of the data-bound dropdown combo. The Area parameter specifies where the user has clicked. The Click event is fired no matter where the user clicks within the dropdown combo, so you have to filter out clicks that don't really affect this program.

The second If...Then statement makes sure a valid record is being pointed to by the data-bound combo box. If an empty record is somehow selected, the SelectedItem property will return the special value Empty. A run-time error will result if you attempt to assign this to the data control's Bookmark property.

Programming the Add Favorites Button

You need to have the Add Favorites button perform two things: First get a title for the page to be added from the user; second, write the URL and title to the Access database. For this example, you can use an InputBox$() function to gather the title.

  1. First, drag a button onto the form.

  2. Set the Caption to &Add Favorite and the Name to cmdAddFav.

  3. With these in place, you can write the code in Listing 4.4. for the cmdAddFav_Click event. This code causes the input box to be displayed whenever the user clicks the Add Favorite button, as shown in Figure 4.3.

Listing 4.4. The Click event code for the cmdAddFav button.

Private Sub cmdAddFav_Click()
Dim strTitle As String
Dim strUrl As String
    strTitle = InputBox$("Please Enter a Title for the Page.", "Add Favorite")
    strUrl = txtURL.Text
    Data1.Recordset.AddNew
    Data1.Recordset!URLTitle = strTitle
    Data1.Recordset!urlAddress = strUrl
    Data1.Recordset.Update
    Data1.Recordset.Bookmark = Data1.Recordset.LastModified
End Sub 

Figure 4.3. Run-time view of the custom browser with the Input box.

Programming the Exit Button


For the Exit button (cmdExit), use the single statement Unload Me, which unloads the single form, and thus the application.

Summary


This section guided you through the creations of a Web browser with the basic capabilities I outlined at the beginning of the section. As you can see, creating a standalone browser, or adding a browser to another application is a simple task with the Webster control. The running application with the Excite Web Search page loaded is shown in Figure 4.4.

Figure 4.4. Run time view of the custom browser.

Microsoft HTML Control


Unless you live under a large, heavy rock, you've heard of Microsoft's ActiveX controls. These 32-bit OLE controls are Microsoft's attempt to integrate applications development, the Microsoft Internet Explorer, and the Internet.

http://www.microsoft.com/icp

The Internet Control Pack (ICP) ActiveX controls are a set of Internet tools. Included are tools for handling the following Internet protocols: FTP, HTML, HTTP, NNTP, SMTP, and POP3. The controls are currently in beta and available via Microsoft's web site at http://www.microsoft.com/icp.

Overview of MS HTML's Properties, Methods, and Events


The following sections describe the various properties, methods, and events supported by the Microsoft ICP's HTML control Beta. The text following property names provides the data type of the property.

BackImage Property (URL as a String)

The BackImage property sets the default background displayed in the browser window. This can be overridden by the HTML <BODY BACKGROUND> tag in the page being viewed.

BaseURL Property (URL as a String)

BaseURL is set to the URL contained in the <BASE> tag of the current page. If no base URL is specified, BaseURL is set to the URL of the current page.

DeferRetrieval Property (Boolean)

The DeferRetrieval property determines if inline images are loaded. A false value tells the browser to load the images; true turns off the loading of inline images.

DocBackColorProperty (Long)

This property is read-only at run-time and not available during design. DocBackColorProperty returns the value of the background color of the HTML document.

DocForeColor Property (Long)

The DocForeColor property is read only at run-time and not available during design. It returns the value of the foreground (text) color of the HTML document.

DocInput Property (DocInput)

The DocInput property returns a reference to the DocInput object. Again, it is read-only during run-time and unavailable during design-time. It enables the programmer to access the properties, methods, and events of the embedded DocInput object of the HTML control.

DocLinkColor Property (Long)

The DocLinkColor property returns the value of the color of the hypertext links that have not been accessed within the HTML document. Like other Doc-related properties, it is read only at run-time and not available during design.

DocOutput Property (DocOutput)

The DocOutput property returns a reference to the DocOutput object, is read-only during run-time, and is unavailable during design time. It enables the programmer to access the properties, methods, and events of the embedded DocOutput object of the HTML control.

DocVisitedColor Property (Long)

The DocVisitedColor property (read-only at run-time and not available during design) returns the value of the color of the hypertext links that have been accessed in the HTML document.

ElemNotification Property (Boolean)

The ElemNotification property is read/write at design- and run-time. When set to true, it triggers the DoNewElement event during HTML parsing.

EnableTimer Property (Boolean)

The setting of EnableTimer determines the behavior of the TimeOut event. The three timeout conditions that can be set via the EnableTimer property are

prcUserTimeout—This is the user-defined timeout.

If any of the timeout times are surpassed without either a connection, receipt of data, or the user-defined event, the timeout event occurs.

The following code demonstrates how to set the EnableTimer property of each of these:

MSHTML1.EnableTimer(prcConnectTimeout)= True
MSHTML1.EnableTimer(prcReceiveTimeout)= True
MSHTML1.EnableTimer(prcUserTimeout)= True

FixedFont Property (Font as a String)

The FixedFont property is read/write at design- and run-time and is the font used to display fixed-width fonts in the HTML page.

Forms Property (HTML Forms)

This property is read-only and returns a reference to the HTML forms collection.

Heading#Font Property (Font as String)

The six properties Heading1Font, Heading2Font, and so on through Heading6Font are the fonts used by the HTML control to display text of the corresponding heading level that appears in the HTML file.

LayoutDone Property (Boolean)

LayoutDone is a read-only at run-time property. It is set to true when the HTML page layout is complete.

LinkColor Property (RGB Value)

LinkColor sets or returns the default link color that will be displayed. It can be overridden by the DocLinkColor property if the UseDocColors property is true.

ParseDone Property (Boolean)

The ParseDone value is set to false when an HTML file begins loading and is set to true when the HTML file is completely parsed.

Redraw Property (Boolean)

The Redraw property determines whether the data should be redrawn whenever the data in the HTML document changes or the user scrolls the browser window.

RequestURL Property (URL as a String)

RequestURL is a read-only property available only at run-time that returns the string value of the URL of the new document that has been requested.

RetainSource Property (Boolean)

The RetainSource value determines whether the HTML control should make the source HTML code available via the SourceText property.

RetrieveBytesDone Property (Long)

This read-only property is available only at run-time and returns the number of bytes that have been retrieved. RetrieveBytesDone returns a value of zero if no retrieval is in progress.

RetrieveBytesTotal Property (Long)

The RetrieveBytesTotal property is a read-only property, available only at run-time, that returns the total number of bytes of the HTML document and its embedded objects.

SourceText Property (String)

If the RetainSource property is true, the SourceText property returns the HTML source of the currently loaded URL.

TimeOut Property (Long)

The TimeOut returns or sets the timeout value in seconds. The timeout period begins when a document is requested. If the document is not received in the number of seconds set in the TimeOut property the TimeOut event is implemented.

TotalHeight Property (Long)

TotalHeight is a run-time, read-only property that returns the height of the current document in pixels.

TotalWidth Property (Long)

Similar to the TotalHeight property, TotalWidth applies to the width of the document.

UnderlineLinks Property (Boolean)

If UnderlineLinks is set to true, the browser displays hyperlinks with underline formatting; if false, no underlining of hyperlinks appears.

URL Property (URL as a String)

Returns the URL of the currently loaded document.



The Help file included with Beta 2 of the ICP indicates that this property is read/write. However, attempting to set this property will result in a run-time error. The VB Object Browser correctly describes this property as I've described above.


UseDocColors Property (Boolean)

When UseDocColors is set to true, the document displays itself using the colors defined by the DocColors properties. If false, it's displayed using the default properties for each element in the page.

ViewSource Property (Boolean)

Setting the ViewSource property to true displays the HTML for the current document.

VisitedColor Property (RGB)

VisitedColor determines the default color for visited links.

Cancel Method

The Cancel method, called without any parameters, causes any current requests for the calling control to be canceled.

RequestAllEmbedded Method

RequestAllEmbedded generates a request for all of the embedded objects in the current document.

RequestDoc Method

The RequestDoc method has a single argument: the URL that is to be requested. After the request, the HTML control begins loading the requested URL.

BeginRetrieval Event

The BeginRetrieval event is implemented when the document retrieval begins.

DocInput Event

The properties and events of the DocInput method can be used to determine the current status while loading a URL. The event is fired when data is received by the HTML control.

DocOutput Event

DocOutput acts much like the DocInput event but is fired when data is being transferred from the control to a URL.

DoNewElement Event

The DoNewElement event is fired when a new element is encountered while an HTML document is being parsed. The parameters are

EnableDefault as a Boolean.

The ElemType is the HTML element type of the parsed source. It returns an empty string for character data. The EndTag Boolean value is true if the element is an end tag, false otherwise. The Attrs is the collection of HTML attributes. Text is the character data—Text is empty if the parsed data is a tag. EnableDefault is a Boolean that, if False, causes the control to continue parsing and ignore the current element, instead of attempting to render it on the control's window. If it is set to True, the element will be rendered using the control's standard processing.

DoRequestDoc Event

The DoRequestDoc event is fired when a new URL is requested. The parameters are

EnableDefault as a Boolean.

The URL is the requested document. The Element is not currently implemented but will identify the anchor of the link selected by the user. DocInput causes the control to accept input from another source. The Boolean EnableDefault enables or disables default processing. The default action varies depending on the type of file being retrieved. For HTTP and File URL, a new instance of the DocInput object is created, and the document is placed in that object. For other URL types, the DocInput property is set.

DoRequestEmbedded Event

DoRequestEmbedded is fired when an image or other embedded object is requested for display. The parameters are the same as for the DoRequestDoc event.

DoRequestSubmit Event

When the user clicks on the Submit button on a form, the DoRequestSubmit event is implemented. The parameters for the event are

EnableDefault as a Boolean

The URL and EnableDefault variables behave just as they do in the other DoRequest events. The Form parameter identifies the HTML form being submitted from the form's collection. The DocOutput object can be used with the EnableDefault to reroute the submission to something other than the HTTP reply by setting it to the DocInput property of another control.

EndRetrieval Event

The EndRetrieval event is fired when the text and inline images of the HTML document are completely retrieved.

LayoutComplete Event

As you may have guessed, LayoutComplete is implemented when the layout of the HTML document is complete.

ParseComplete Event

ParseComplete is fired when the entire HTML document has been parsed.

TimeOut Event

This event is fired when the amount of specified time in the TimeOut property passes without the corresponding event having occurred. The parameters for the TimeOut event are

Continue as a Boolean

The Event argument is the process that caused the current TimeOut, as defined by:

prcConnectTimeout (1)

A connection was not established within the timeout period

prcReceiveTimeout (2)

No data arrived within the timeout period

prcUserTimeout (65)

Timeout for a user defined event. User should use prcUserTimeout + [Integer] range for custom timeout events.


This event will fire only if EnableTimer for the specific event is set to True.

When Continue is set to true, the TimeOut condition is passed and normal processing resumes.

UpdateRetrieval Event

The UpdateRetrieval event happens periodically during the retrieval of text and images. The RetrieveBytesTotal and RetrieveBytesDone properties can be used during this event. These values can be used to generate user feedback about the progression of the retrieval of the page. For example:

Sub HTML1_UpdateRetrieval()
    StatusBar1.SimpleText = "Retrieved " & HTML1.RetrieveBytesDone & _
                            " of " & HTML1.RetrieveBytesTotal & " bytes."
End Sub

Designing the Form


After installing the controls, the help file appears in the Windows 95 Start menu, and the controls can be added under the Custom Controls menu item (CTRL-T) in Visual Basic 4. The controls are currently still in beta, and the help files are not yet complete. Keeping this in mind, I'll show you a basic Web browser that could be used for online help, an Intranet application, or to limit the sites the user can visit.

To start, you add the Microsoft HTML client control; the control appears in the toolbox. Next, size the tool to the desired size for the browser's viewing window. To round off the browser, add a label indicating the current location, a status bar for user feedback, and a control array of command buttons that enable users to access specific sites or exit the application. The form should look similar to Figure 4.5.

Figure 4.5. A design-time view of the browser.

To accommodate the users' resizing of the form during run-time, add the code in Listing 4.5 to the Form_Resize event:

Listing 4.5 Code for the Form_Resize event.

    HTML1.Top = 1000
    HTML1.Left = 50
    If ScaleWidth > 2000 Then
        HTML1.Width = ScaleWidth - 1600
        For x = 0 To 6
            cmdGo(x).Left = ScaleWidth - 1400
        Next x
    End If
    If ScaleHeight > 490 Then
        HTML1.Height = ScaleHeight - 1490
    End If 

The first two lines allow for an unused area to the left of the browser, and the 1000 twips at the top of the form are reserved for the label and textbox that indicate the current URL. The first If...Then block checks to see whether the width has been reduced to a size too small for the buttons. If the new size is large enough, the buttons are moved also. The last three lines of code in Listing 4.5 check the height and resize to make room for the status bar.

Programming the Textbox


You want this textbox to behave in two directions, both as a method for user entry of the desired URL to visit, and as a display of the current URL. Thus, if a user types a URL and presses enter, that URL is loaded and displayed. When the user follows a hyperlink on that page, the URL of the page followed is displayed. With the Microsoft HTML control, this is a relatively easy task. The code for the textboxes follows.

For the keypress event of the textbox, you want the following code:

    If KeyAscii = 13 Then
        SendKeys "{TAB}"
    End If

This causes the Tab key to be "pressed," if the user hits the Enter key. The side effect of the Tab being pressed is the LostFocus event, which has the following code:

HTML1.RequestDoc txtUrl.Text

The RequestDoc method of the Microsoft HTML control takes a string as its single argument. This string must be a valid URL or HTML file. With this in place, the control begins to load and display the URL.

Programming the Command Buttons


As you may have guessed with the simplicity of the RequestDoc method of the ICP HTML control, placing command buttons that load a specific site is an elementary task. The code for the Click event of the control array of command buttons is shown in Listing 4.6.

Listing 4.6. The cmdGo_Click event procedure code.

Private Sub cmdGo_Click(Index As Integer)
Select Case Index
        Case 0  'home
            HTML1.RequestDoc "http://execpc.com/~haasch"
        Case 1  'yahoo
            HTML1.RequestDoc "http://www.yahoo.com"
        Case 2  'Microsoft
            HTML1.RequestDoc "http://www.microsoft.com"
        Case 3  'Espn
            HTML1.RequestDoc "http://espnet.sportszone.com"
        Case 4  'ZD
            HTML1.RequestDoc "http://www.zd.com"
        Case 5  'Excite
            HTML1.RequestDoc "http://www.excite.com"
        Case 6
            Unload Me
    End Select
End Sub

Like I said—easy.

Melding the Status Bar and the HTML Control


Like the Webster application earlier in the chapter, you'll want to provide the user with feedback about the state of the browser. You can use the events of the HTML control to set the SimpleText property of the status bar.

After setting the Style property of the status bar control to 1—single panel, simple text—you can change the SimpleText property of the status bar in the corresponding events of the HTML control. The procedures involved are shown in Listing 4.7.

Listing 4.7 HTML1 event procedure code.

Private Sub HTML1_BeginRetrieval()
    txtUrl = HTML1.URL
    StatusBar1.SimpleText = "Retrieving " & txtUrl
End Sub
Private Sub HTML1_EndRetrieval()
    StatusBar1.SimpleText = "Completed Loading " & HTML1.URL
End Sub
Private Sub HTML1_UpdateRetrieval()   
    StatusBar1.SimpleText = "Retrieved " & HTML1.RetrieveBytesDone & _
                         " of " & HTML1.RetrieveBytesTotal & " bytes."
End Sub

As you can see, this event also updates the URL displayed in this textbox to the URL currently being retrieved.

With this code in place, you have a working browser based on the Microsoft HTML control. The running application is shown in Figure 4.6.

Figure 4.6. The run-time view of the browser using the Microsoft HTML Control.

Comparing The ICP And The Sax Webster HTML Controls


As you have seen, both of these controls can add a World Wide Web browser to your application in a matter of minutes. Both are relatively new controls, and although only two are available at this time, Web browser controls will become more widespread soon.

Unfortunately, with only a beta and no documentation of the Microsoft HTML control, I was pretty limited evaluating it. However, it did prove to work well and provided enough functionality to build a simple browser.

The Forms collection contained in the Microsoft control is very handy if you're designing applications that will use HTML-based forms. You can use the DoRequestSubmit event to trap the user clicking the Submit button and then utilize the Forms collection to determine what the user has entered on the form. What you do with this information is entirely up to you and your needs, but it leaves the imagination with lots of possibilities, especially for Intranet applications.

The Webster control evaluated was 1.07. This update to the 1.0 version fixed several small bugs and allows the PageURL to be set to a string without the http:// in front of it. I had some problems with certain graphics displaying correctly, but the incidence of this was in less than 10 percent of the pages I visited.

The Webster control offers a lot of functionality to the programmer. For a quick application, leave the Sax toolbar in place. This accomplishes most of the work with no code. On the other extreme, if you want to make it a truly custom browser, the Webster control provides enough properties, methods, and events to make it a serious tool for adding a browser to any application.

Crescent CIHTML Control


Crescent has also thrown its hat into the Internet game with its Internet ToolPak. This set of controls includes an FTP client control, a Web control that provides accessibility to Web documents, a mail control that includes SMTP and POP3 compatibility, a news control (NNTP protocol), and a TCP/IP control.

Crescent's CIHTML control does not claim to be a browser in a control. Rather, it focuses on Web information retrieval and manipulation.

Properties, Events, and Methods of the CIHTTP Control


In this summary of properties, methods, and events, I only cover those that are specific to the CIHTTP control. For information on the standard Visual Basic properties, methods, and events consult your manuals or help file.

AnchorListBoxName Property (String)

AnchorListBoxName is an optional property. If a listbox name is assigned to it and a page is retrieved, the anchors of the retrieved page appear in the listbox.

EventState Property (Integer)

The EventState property returns the value of the event currently taking place. The events supported are

ListBoxes Populated

120

HTTPServer Connection

121

Socket Closed

122

HTTPServer Connection Closed

123

File Closed

124



HostAddress Property (String)

The HostAddress property can be set with or returns the value of the Internet host's IP address. (for example, 156.46.10.10)

Either the HostAddress or the host name must be specified. The host name takes the more popular Domain Name Server (DNS) name (www.mycompany.com) and uses that to derive the IP address.

If going through a server proxy/firewall (a machine that, for security reasons, sits between the global Internet and an organizations local area network), a ProxyServerName or ProxyServerAddress must also be specified.

HostName Property (String)

HostName is similar to the HostAddress property, but the host is specified by its DNS name rather than its IP address.

HTMLPageTextWithoutTags Property (String)

HTMLPageTextWithoutTags is a read-only at run-time property that returns the HTML page without the formatting tags.

HTMLPageTextWithTags Property (String)

HTMLPageTextWithTags works much like the HTMLPageTextWithoutTags property, but leaves the HTML tags intact. The ParseIncomingData property (described below) must be true for this to work correctly.

HTTPPort Property (Integer)

The HTTPPort property, which defaults to 80, sets the port used for HTTP communications.

ImageFileListBoxName Property (ListBox)

The ImageFileListBoxName property corresponds to the AnchorListBoxName property. However, instead of storing the names of anchors, it stores the names of images.

LocalFileName Property (String)

The path/filename combination in LocalFileName is the location where information retrieved via the CIHTTP GET method is stored.

MethodState Property (Integer)

MethodState works similar to the EventState property but applies to the GET, HEAD, and POST methods. The properties possible values are:

GET

14

HEAD

15

POST

16



ParseIncomingData Property (Boolean)

If the value of ParseIncomingData is true, the control parses the data; otherwise, the control assumes the information is binary.

ProxyServerAddress Property (String)

If the user is going through a server proxy (firewall) either the IP address or the name of the firewall must be stored in either the ProxyServerAddress property (IP Address) or the ProxyServerName property (DNS Name).

ProxyServerName Property (String)

The DNS name of the user's firewall (if any) must be stored in the ProxyServerName property or the firewall's IP address stored in the ProxyServerAddress property.

TagListBoxName Property (ListBox)

TagListBoxName works similar to its ImageFileListBoxName and AnchorListBoxName counterparts: While the CIHTTP control parses the incoming page, the HTML tags are placed in the specified listbox.

URL Property (String)

This sets or retrieves the URL of the currently loading, or loaded request.

WWWSiteName Property (String)

The WWWSiteName property contains the title of the currently loaded page. The title is retrieved from the <TITLE> element of the HTML file.

CleanupConnection Method

Use CleanupConnection to clear any errors that occur when a GET, HEAD, or POST method occurs, or if the control is having problems reopening a socket.

ConnectToHTTPServer Method

Once the HostName or HostAddress properties are set (ProxyServerName/ProxyServerAddress if necessary) ConnectToHTTPServer attempts to connect to the specified server. If successful, it returns the socket number opened for the connection as an integer. If failed, it returns 0 and fires the WSAError event.

GET Method

After connecting to the Web server and setting the URL, the GET method retrieves the page specified by the URL.

HEAD Method

The HEAD method retrieves the page information from the specified URL.

POST Method

After the URL is set, the POST method sends the text to that URL.

SendHTTPCommand Method

The SendHTTPCommand method enables you to issue HTTP commands other than GET, HEAD, and POST. The method's single argument is the HTTP command that is to be sent. This can be used to talk to servers that support HTTP request message extension methods as described in the "HTTP Request Messages" section of Chapter 2, "HTTP: How to Speak on the Web."

EventStateChanged Event

This event fires when the EventState property changes.

FileClosed Event

The FileClosed event is implemented when the file specified by the LocalFileName property is closed.

HTTPServerConnectionClosed Event

HTTPServerConnectionClosed is fired when a connection to a Web server is closed.

ListBoxesPopulated Event

This event fires after all of the AnchorListBox, ImageListBox, and TagListBox list boxes have been filled.

MethodStateChanged Event

MethodStateChanged occurs when the MethodState property changes.

MethodStateChanged Event

The MethodStateChanged event is implemented when a packet is received from the connected Web server.

PacketSent Event

PacketSent takes place when a packet is sent to the connected Web server.

SocketClosed Event

The SocketClosed event fires when the socket your control is using is closed. This should happen only after your application is done running. If SocketClosed occurs, the application should reopen a socket and retry the command that caused the error.

TotalFileBytesReceived Event

The single parameter in the TotalFileBytesReceived event is the bytes_in value. This value is incremented each time a packet is received from the server.

WSAError Event

WSAError fires when a Winsock error occurs. The single argument error_number is the Winsock error.

Summary


The Webster control is the first-released browser-in-a-box ready to be popped into any Visual Basic application. Its inclusion of command buttons and easy property manipulation makes it a breeze to use.

Microsoft's HTML client control, although in Alpha stages, looks promising. It, too, is an integrated browser, but look for future releases of the control to support VB Script, OLE, and a host of other Internet technologies that Microsoft has up its sleeve.

Crescent's CIHTTP control takes a different approach, offering a way to retrieve, and easily parse HTML files. This can be used to create agents, spiders, and custom applications that draw off of information available via the World Wide Web.

The three tools you looked at are the first "web-aware" tools to appear in the marketplace. As time progresses, I'm sure the tools will evolve as user demand and evolution of the Web protocols continue. Now it is up to the developers to find useful applications for these Web tools.

Previous Page Page Top TOC Next Page See Page