Communicating with the Browser

Many of the Applet and AppletContext methods involve some sort of communication with the browser or applet viewer. For example, the Applet getDocumentBase() and getCodeBase() methods get information from the browser or applet viewer about where the applet and its HTML page came from. The Applet showStatus() method tells the browser or viewer to display a status message. The Applet getParameterInfo() method can give a browser a list of the parameters an applet understands. And, of course, the browser or applet viewer calls the Applet init(), start(), stop(), and destroy() methods to inform the applet of changes in its state. All these methods are discussed elsewhere in this trail.
Also interesting are the AppletContext showDocument() methods. With these methods, an applet can control which URL the browser shows, and in which browser window. (By the way, the Applet Viewer ignores these methods, since it isn't a Web browser.) Here are the two forms of showDocument():
public void showDocument(java.net.URL url)
public void showDocument(java.net.URL url, String targetWindow)
The one-argument form of showDocument() simply tells the browser to display the document at the specified URL, without specifying the window to display the document in.
The two-argument form of showDocument() lets you specify which window or HTML frame to display the document in. The second argument can have the values listed below.
Terminology Note: In this discussion, frame refers not to an AWT Frame but to an HTML frame within a browser window.

"_blank"
Display the document in a new, nameless window.
"windowName"
Display the document in a window named windowName. This window is created if necessary.
"_self"
Display the document in the window and frame that contain the applet.
"_parent"
Display the document in the applet's window but in the parent frame of the applet's frame. If the applet frame has no parent frame, this acts the same as "_self".
"_top"
Display the document in the applet's window but in the top-level frame. If the applet's frame is the top-level frame, this acts the same as "_self".

Below is an applet that lets you try every option of both forms of showDocument(). It brings up a window that lets you type in a URL and choose any of the showDocument() options. When you press return or click the Show document button, the applet calls showDocument().

You can't run 1.0 applets, so here's a picture of the window this applet brings up:

Browser Note: In Netscape Navigator 2.0 for Solaris, at least, this applet is a bit fragile. It simply stops working after a while, and then you have to reload the applet to get it to work again. Specifying "My Personal Window" (one of the choices in the pop-up list) or "_blank" seems to work well. When you specify anything else, though, the applet seems to work just once and then stop working for any subsequent choice.
Below is the applet code that calls showDocument(). (Here's the whole program.)
	...//In an Applet subclass:
        urlWindow = new URLWindow(getAppletContext());
	. . .

class URLWindow extends Frame {
    . . .
    public URLWindow(AppletContext appletContext) {
	. . .
        this.appletContext = appletContext;
	. . .
    }
    . . .
    public boolean action(Event event, Object o) {
	. . .
	    String urlString = /* user-entered string */;
            URL url = null;
            try {
                url = new URL(urlString);
            } catch (MalformedURLException e) {
		...//Inform the user and return...
            }

            if (url != null) {
                if (/* user doesn't want to specify the window */) {
                    appletContext.showDocument(url);
                } else {
                    appletContext.showDocument(url, /* user-specified window */);
                }
            }
        . . .

Communicating with Other Programs