The JavaTM Tutorial
Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search
Feedback Form

Trail: Writing Applets
Lesson: Taking Advantage of the Applet API

Displaying Documents in the Browser

Have you ever wanted an applet to display formatted HTML text? Here's the easy way to do it: Ask the browser to display the text for you.

With the AppletContext showDocument methods, an applet can tell the browser which URL to show and in which browser window. (By the way, the JDK Applet Viewer ignores these methods, since it can't display documents.) 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.


Terminology Note:  In this discussion, frame refers not to an AWT Frame but to an HTML frame within a browser window.

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.

"_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".

The following applet lets you try every option of both forms of showDocument. The applet 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 applets, so here's a picture of the window this applet brings up:



Note: If you don't see the applet running above, you need to install Java Plug-in, which happens automatically when you install the J2SE JRE or SDK. We strongly recommend that you install the latest version; at least 1.3.1 is required for all our applets. You can find more information in the Java Plug-in home page.

Following is the applet code that calls showDocument. (Here's the whole program (in a .java source file).)

	...//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 */);
                }
            }
        . . .

Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search
Feedback Form

Copyright 1995-2005 Sun Microsystems, Inc. All rights reserved.