API documentation is available from
This document contains the following sections:
The ICEBrowser bean is simply a container with a Browser bean and controls inside.
The ICE Browser beans can render hypertext from a number of sources:
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
The ICE Browser can simply be run as a standalone browser from your JVM. We
provide examples here using the JDK from JavaSoft.
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 using a graphical tool to implement your application
(for example JBuilder, JavaWorkshop, X-Designer...), you should import the
ICE Browser JAR file using the mechanisms provided by those tools. The tools
will allow you to incorporate ICE Browser into your application
and to manipulate the ICE Browser bean properties. You should refer
to your tool's documentation to find out how to manipulate
bean properties.
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
The Browser class is an extension of the core AWT Panel
class. This means that you can simply integrate ICE Browser into your
application anywhere you can use a Panel.
|
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
In ICE Browser we ensure that the
Document class fires any mouse events in the
HTML window. This means that programmers can easily modify the behaviour
of ICE Browser when the user clicks in the HTML window. We illustrate
this feature with an example that shows a pop-up menu whenever the
user clicks on the right mouse button.
|
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
As well as functioning as a standalone or embedded
Browser, ICE Browser is popular for use as
a simple HTML Document renderer panel.
We shall illustrate this use by example.
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);variant. This will direct the Document class to append HTML text from a string generated by the program.
There are also htmlAppend() methods with the following signatures:
public void htmlAppend(String loc, String outputString); public void htmlAppend(Reader reader, String mimeType);The latter is the most versatile of these methods. Since there are a number of I/O classes that extend the java.io.Reader class, this method can be used to append HTML into ICE Browser from virtually any source.
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
It is possible to monitor changes to the Document
status using standard PropertyChangeEvent methods provided
by JDK.
Please see the example program demo3.java
for an example. In this example we implement a simple status
bar. The status bar is modified every time the mouse is
over a link, to show where that link leads to. The window
title bar is also modified when the document title changes.
Implemented properties are:
http://www.icesoft.no/ICEBrowser/test.jar#info.htmlThis would load the JAR file test.jar and access the resource info.html from inside it. After that all relative URL's are expanded to use the JAM protocol.
java -Dhttp.proxyHost="your.proxy.host" -Dhttp.proxyPort=your-proxy-portThis feature has been tested with JDK 1.1.