Programmers User Guide for ICE Browser v4.0

API documentation is available from

This document contains the following sections:

ICE Browser ice.htmlbrowser.ICEBrowser.

This is a standalone browser, which can also be used as a bean. It has optional controls for traversing the history stack, and an editable location field showing the current location.

The ICEBrowser bean is simply a container with a Browser bean and controls inside.

ICE Document Bean ice.htmlbrowser.Document.

This is the main document rendering class. It extends the AWT Panel class and can be incorporated directly into applications as either a bean, or as an AWT object.

ICE Browser Component Bean ice.htmlbrowser.Browser.

This is an extension of the Document class, but with the addition of history and cache management.

The ICE Browser beans can render hypertext from a number of sources:

• HTTP connections.
• Anonymous FTP connections.
• Java Archive (JAR) files.
• Local file system.
• Readers from Java applications.
• Custom protocols and filters.

The main structural difference is that Browser now extends Document instead of containing one. If you were previously using the Browser class and the demonstration navigation controls, you should now use the ICEBrowser class for this purpose.

Overhauling the code has brought a number of improvements. Threads are now managed better, and the memory cache can be controlled.

Getting Started

First, you need to set the CLASSPATH to point to the ICE Browser JAR file, then launch ICE Browser from the command line.

For example with UNIX csh:

setenv CLASSPATH your-ICE-path/icebrowserbean.jar
java ice.htmlbrowser.ICEBrowser

With Windows95, from the MS-DOS prompt:

set CLASSPATH=your-ICE-path\icebrowserbean.jar
java ice.htmlbrowser.ICEBrowser

You can also add a URL to the command line

java ice.htmlbrowser.ICEBrowser http://www.javasoft.com

The standalone browser has a simple interface allowing you to go back/forward through the history list and reload the current page. You can also enter the url of the location you wish to visit using the text field above the main window. Please note that this minimal interface is provided only to illustrate how to get started with ICE Browser. We expect all user's to override this and provide a custom browser interface for their application.

Advanced Use

If you are interfacing your application to ICE Browser by writing Java code, the you should read the remainder of this documentation. The main class that you should consider is the Browser class. In some special circumstances you may also be interested in accessing the Document class directly if you are ONLY interested in rendering HTML and not in navigating hyperlinks. We briefly discuss various typical uses of the ICE Browser beans in the next 3 sections below and refer to the relevant example programs delivered with ICE Browser. The final section explains a programmer tips that will help you to fully customize ICE Browser to meet your needs.

Creating a custom browser

        // ICE Browser - simple demo example for version 4.0
         
        import ice.htmlbrowser.Browser;
         
        import java.awt.*;
        import java.awt.event.*;
         
         
        public class demo1 extends Frame
        implements WindowListener
        {
                public demo1(String loc) {
1                        addWindowListener( this );
                        setLayout(new BorderLayout());
                // Start up the browser
2                        iceBrowser = new Browser();
3                        iceBrowser.gotoLocation(loc);
4                        add("Center",iceBrowser);
                }
         
                private ice.htmlbrowser.Browser iceBrowser;
         
                public static void main(String args[]) {
                        demo1 d = new demo1("http://www.icesoft.no/");
                        d.setSize(500,300);
                        d.show();
                }
         
                // WindowListener interface
                public void windowClosing( WindowEvent event ) { dispose(); }
                public void windowOpened( WindowEvent event ) {}
                public void windowIconified( WindowEvent event ) {}
                public void windowDeiconified( WindowEvent event ) {}
                public void windowClosed( WindowEvent event ) { System.exit(0);}
                public void windowActivated( WindowEvent event ) {}
                public void windowDeactivated( WindowEvent event ) {}
        }

In the simple example above lines are numbered for description only. This example is available as demo1.java in the examples directory of the ICE Browser.

The demo program would normally be started from the command line and execute its main() method. This creates a new demo1 object. The first thing demo1 does in this case is to add itself as the WindowListener (1) so that we can kill the application from the frame menu. Then we must construct a new Browser object (2). At this stage we can add the Browser object to our Frame, but in our example we have chosen to leave this until last (4). In order to point our Browser at an initial WEB site, we call the gotoLocation() method (3).

An extended example

        // ICE Browser - an extended example illustrating some finer points

        import ice.htmlbrowser.Browser;
        import java.awt.*;
        import java.awt.event.*;

1       public class demo2 extends demo1 
                implements MouseListener {

                public static void main(String args[]) {
                        Frame d = new demo2("http://www.icesoft.no");
                        d.setSize(500,300);
                        d.show();
                }

                public demo2(String loc) {
                        super(loc);
2                       pup = new NavPopup(iceBrowser);
                        add(pup);
3                       iceBrowser.addMouseListener(this);
                }

                protected PopupMenu pup;

                // MouseListener interface (for trapping mice) 

                /**
                  * UNIX and Win95 popupTrigger behave differently, so
                  * we need to handle this in processMouseEvent() (which
                  * we cant do here) or in both mousePressed and mouseReleased
                  */
                private void processPopup(MouseEvent e) {
                        if (e.isPopupTrigger()) {
                                Object o = e.getSource();
                                if (o instanceof Component)
                                        pup.show((Component)o, e.getX(), e.getY());
                        }
                }

4               public void mousePressed(MouseEvent e) {
                  processPopup(e);
                }
         
                public void mouseClicked(MouseEvent e) { }
4               public void mouseReleased(MouseEvent e) { 
                  processPopup(e);
                }
                public void mouseEntered(MouseEvent e) { }
                public void mouseExited(MouseEvent e) { }
        }

5       class NavPopup extends PopupMenu implements ActionListener {
                MenuItem back = new MenuItem("Back");
                MenuItem fwd = new MenuItem("Fwd");
                MenuItem reload = new MenuItem("Reload");
         
                public NavPopup(Browser browser) {
                        super("Navigation");
                        add(back);
                        add(fwd);
                        add(reload);
                        addActionListener(this);
                        this.browser = browser;
                }
         
        // ActionListener Interface
                public void actionPerformed(ActionEvent e) {
                        String cmd = e.getActionCommand();
                        if ("Back".equals(cmd)) browser.goBack();
                        else if ("Fwd".equals(cmd)) browser.goForward();
                        else if ("Reload".equals(cmd)) browser.reload();
                }

                private Browser browser;
        }

In this example, we build on the previous example, and in the true spirit of object oriented programming, we extend the functionality of demo1 (1) and add a MouseListener interface. demo2 introduces a popup menu, so this is created in the constructor (2). In order to be able to detect a right mouse press, we register this class as a MouseListener of our Browser object (3). When any mouse button is pressed, the mousePressed() method in demo2 will be fired (4). Note that Win95 and UNIX Popup triggers are different, and it is necessary to check for a Popup trigger in both mousePressed() (UNIX) and mouseReleased() (Win95).

One thing to watch for is that the Object returned in the mousePressed() method probably will not be the same as the iceBrowser object that is the registered listener. This is because the underlying ICE Browser Document class has several AWT objects inside it, however this should not be a concern, since the object, and the coordinates of the event are preserved when the event is passed up to Document, and the pop-up menu will appear in the correct place. Note further that the Browser class is an AWT Container, and as such should not normally provide mouse events, however we feel that is is sensible for the Browser class to pass these events on rather than the programmer requiring low level knowledge of the contained components in Browser.

Finally note that the pop-up menu itself is based on the AWT PopupMenu class (5). Please note that our NavPopup class is only to illustrate how to use mouse events. Since it uses hard-coded strings to determine the menu choice it is not portable. For readers with small children - you should not try this at home.

Creating a document renderer/providing input from a Reader

ICE Browser also includes methods to provide and append HTML text from a Reader. Infact this is how HTML is provided to the internal Parser. We shall illustrate appending HTML text programmatically in the same example.

The htmlClear() and htmlAppend() initialise and append to the currently displayed Document. The htmlAppend() method is overloaded to provide several HTML sources. The one we shall review here is the

        public void htmlAppend(String htmlSource);

There are also htmlAppend() methods with the following signatures:

        public void htmlAppend(String loc, String outputString);
        public void htmlAppend(Reader reader, String mimeType);

Many ICE Browser customers have special requirements, for example accessing HTML from within a database. In most cases this can be achieved by implementing a simple custom protocol handler that is called when the custom protocol is used in a URL. The custom protocol handler can then provide html text through the standard URLConnection class.

Listening for Document events

Implemented properties are:

• currentFrame
• currentLocation
• documentBase
• documentTitle
• statusString

        http://www.icesoft.no/ICEBrowser/test.jar#info.html

Firewall access

ICE Browser is capable of accessing web pages through a firewall if a proxy server has been set up at your intranet site for this purpose. In order to inform ICE Browser about the proxy server you must set two properties - http.proxyHost and http.proxyPort. One way to do this is to set these when you start the Java run time system. For example with JDK:

        java -Dhttp.proxyHost="your.proxy.host" -Dhttp.proxyPort=your-proxy-port

This feature has been tested with JDK 1.1.