Creating embedded browsers

EBASIC allows creating a self contained internet browser attached to a window. The embedded browser functions require Internet Explorer 4.0 or greater to be installed on the system. To embed a browser open a window and use the ATTACHBROWSER command. @NOAUTODRAW should be used as a window style to prevent any overwriting of the displayed HTML document. ATTACHBROWSER returns -1 if the browser could not be created or 0 if it was successfully attached to the window.

DEF wb as WINDOW
OPENWINDOW wb,0,0,640,480,@SIZE|@NOAUTODRAW|@MINBOX|@MAXBOX,0,"Test Browse",&main

IF ATTACHBROWSER(wb,"http://www.ionicwind.com") = -1
    MESSAGEBOX wb, "Couldn't create browser control","Error"
    END
ENDIF

run = 1
WAITUNTIL run=0
CLOSEWINDOW  wb
END

SUB main
SELECT @MESSAGE
    CASE @IDCLOSEWINDOW
        run = 0
ENDSELECT
RETURN
ENDSUB

The browser automatically adjusts its size to the containing window. No extra action is required.

As indicated in the above example, controlling the embedded browser is done with BROWSECMD. BROWSECMD serves as both a statement and a function depending on the command issued. The syntax of BROWSECMD is:

Command	Details
@NAVIGATE, strURL	Navigates to the specified web page or local file.
@GOHOME	Loads the default 'home' page
@GOBACK	Moves back one page in the history list.
@GOFORWARD	Moves ahead one page in the history list.
@BROWSESEARCH	Navigates to the search page specified in the users internet options.
@BROWSESTOP	Stops loading of the current document.
@REFRESH	Refreshes the current document.
@GETTITLE, strTitle {,cchTitle}
@BACKENABLED	Returns 1 if there is at least one page to @GOBACK to or 0 otherwise.
@FORWARDENABLED	Returns 1 if there is at least one page to @GOFORWARD to or 0 otherwise.
@CANCELNAV	Cancels navigation to the current page. Use in response to @IDBEFORENAV to limit navigation.
@GETPOSTDATA, pstrData {,cchData}	Available when @IDBEFORENAV is sent.
@GETHEADERS, pstrHeaders {,cchHead}	Available when @IDBEFORENAV is sent.
@GETNAVURL, pstrURL {,cchURL}	Available when @IDBEFORENAV or @IDNAVCOMPLETE is sent.
@BROWSELOAD, strHtml	Loads the browser with the contents of a string.
@BROWSEPRINT	Prints the currently displayed document. No Parameters.
@GETSTATUSTEXT, pstrStatus {,cchStatus}	Gets the status text to display in a status bar. Available when the @IDSTATUSTEXTUPDATE message is sent

The commands that return string data do so through the string parameter supplied. The optional parameter is always the length of the supplied string and defaults to 255, the length of a standard STRING type. For example getting the status text might look like this:

For readability we will include the length parameter in our examples even when using standard strings.

The @NAVIGATE command allows specifying either a network URL or path to a local file or directory. When used with a directory path the browser will display an Explorer like window allowing standard file operations. The embedded browser can display any of the file types that are viewable in Internet Explorer including pictures, plug-ins, and html documents.

BROWSECMD window, @NAVIGATE, "c:\\"
BROWSECMD window, @NAVIGATE, "e:\\images\\picture.jpg"
BROWSECMD window, @NAVIGATE, "http://www.ionicwind.com"
BROWSECMD window, @NAVIGATE, "ftp://ftp.ionicwind.com"

The embedded browser will send an @IDBEFORENAV message to the window just before it navigates to a page. If you wish to limit access to certain websites or files you can call BROWSCMD with a command of @CANCELNAV. This message can also be used to extract the data from an HTML form.

Once navigation is complete the browser will send an @IDNAVCOMPLETE message. Use this message to redirect to a different URL or to save data gathered during an @IDBEFORENAV message.

During operation of the browser control your handler will also receive @IDSTATUSTEXTUPDATE messages. Use the BROWSECMD @GETSTATUSTEXT to retrieve the text to display. For example when hovering over links the status text sent would be the URL of the link.

DEF wb as WINDOW
DEF data,url as STRING
OPENWINDOW wb,0,0,640,480,@SIZE|@NOAUTODRAW|@MINBOX|@MAXBOX,0,"Test Browse",&main

ATTACHBROWSER wb

BROWSECMD wb,@NAVIGATE,"c:\\forms\\userdata.html"

run = 1
WAITUNTIL run=0
CLOSEWINDOW  wb
END

SUB main
SELECT @MESSAGE
    CASE @IDCLOSEWINDOW
        run = 0
    CASE @IDBEFORENAV
        BROWSECMD(wb,@GETNAVURL, url, 255)
        IF url <> "c:\\forms\\userdata.html"
            BROWSECMD(wb,@GETPOSTDATA, data, 255)
        ENDIF
    CASE @IDNAVCOMPLETE
        BROWSECMD(wb,@GETNAVURL, url, 255)
        IF url <> "c:\\forms\\complete.html"
            BROWSECMD wb,@NAVIGATE,"c:\\forms\\complete.html"
       ENDIF
ENDSELECT
RETURN
ENDSUB

In the above example we first navigate to an html page containing a form. In response to @IDBEFORENAV we check the URL to see if it is not the first page we navigated to. This means the user has pressed the 'send' or 'post' button. Then we retrieve the posted data. In a real world example we would parse the data in the string and act upon it. If one of the fields was in error then the @CANCELNAV command could prevent the user from continuing on.

Posted data normally consists of name-value pairs separated by the '&' symbol. If our form had two fields 'first' and 'last' and the user entered John Smith the string returned would be:

Be careful when navigating to a page in response to @IDNAVCOMPLETE. If you do not test the current URL, the browser will end up in a loop since every page sends the message.

Don't use the @NAVIGATE command in response to an @IDBEFORENAV message. Doing so will send the browser into an endless loop and end your program without warning.

See Also: The browser_test.eba sample program for a fully functional web browser based on the embedded browser control.