Start of Tutorial > Start of Trail > Start of Lesson

Search Feedback Form

How to Make Applets

This section covers JApplet -- a class that enables applets to use Swing components. JApplet is a subclass of java.applet.Applet, which is covered in the Writing Applets trail. If you've never written a regular applet before, we urge you to read that trail before proceeding with this section. The information provided in that trail applies to Swing applets, with a few exceptions that this section explains.

Any applet that contains Swing components must be implemented with a subclass of JApplet. Here's a Swing version of one of the applets that helped make Java famous -- an applet that animates our mascot, Duke, doing cartwheels:

This is a picture of the applet's GUI. To run the applet, click the picture. The applet will appear in a new browser window.

You can find the main source code for this applet in TumbleItem.java. You will also need one other source file and the image files that compose the animation. See the examples index for links to all the files required by this example.

This section discusses the following topics:

• Features Provided by JApplet
• Threads in Applets
• Using Images in a Swing Applet
• Providing an OBJECT/EMBED Tag for Java Plug-in
• The JApplet API
• Applet Examples

Features Provided by JApplet

JApplet adds two major features to the functionality that it inherits from java.applet.Applet. First, Swing applets provide support for assistive technologies. Second, because JApplet is a top-level Swing container, each Swing applet has a root pane. The most noticeable results of the root pane's presence are support for adding a menu bar and the need to use a content pane.

As described in Using Top-Level Containers, each top-level container such as a JApplet has a single content pane. The content pane makes Swing applets different from regular applets in the following ways:

• You add components to a Swing applet's content pane, not directly to the applet. Adding Components to the Content Pane shows you how.
• You set the layout manager on a Swing applet's content pane, not directly on the applet.
• The default layout manager for a Swing applet's content pane is BorderLayout. This differs from the default layout manager for Applet, which is FlowLayout.
• You should not put painting code directly in a JApplet object. See Converting to Swing for information on converting applet painting code, and Working with Graphics for examples of how to perform custom painting in applets.

---

JDK 1.1 Note:  If you run a Swing applet using JDK 1.1 and JFC 1.1, then you might see an error message that looks like this:

Swing: checked access to system event queue.

You can often avoid this message by telling the applet not to check whether it has access to the system event queue. To do so, put the following code in the constructor for the applet class:

getRootPane().putClientProperty(
                  "defeatSystemEventQueueCheck",
                  Boolean.TRUE);

---

Threads in Applets

Because applets inherently use multiple threads and Swing components aren't thread safe, you should take care with threads in Swing applets. It's generally considered safe to create and manipulate Swing components directly in the init method. However, the other milestone methods -- start, stop, and destroy -- might cause trouble when the browser invokes them after the applet's already visible. To avoid trouble, you should make these methods thread safe.

For example, when you implement a stop or start method, be aware that the browser doesn't call them from the event-dispatching thread. Thus, those methods shouldn't affect or query Swing components directly. Instead, they should use techniques such as using the SwingUtilities.invokeLater method to affect components.

For more information about using threads, see Threads and Swing and How to Use Threads.

Using Images in a Swing Applet

The Applet class provides the getImage method for loading images into an applet. The getImage method creates and returns an Image object that represents the loaded image. Because Swing components use Icons rather than Images to refer to pictures, Swing applets tend not to use getImage. Instead Swing applets create instances of ImageIcon--an icon loaded from an image file. ImageIcon comes with a code-saving benefit: it handles image tracking automatically. Refer to How to Use Icons for more information.

The animation of Duke doing cartwheels requires 17 different pictures. The applet uses one ImageIcon per picture and loads them in its init method. Because images can take a long time to load, the icons are loaded in a separate thread implemented by a SwingWorker object. Here's the code:

public void init() {
    ...
    imgs = new ImageIcon[nimgs];
    final SwingWorker worker = new SwingWorker() {
        public Object construct() {
            URL baseURL = getCodeBase();
            String prefix = dir + "/T";
    
            //Images are numbered 1 to nimgs,
            //but fill array from 0 to nimgs-1
            for (int i = 0; i < nimgs; i++) {
                imgs[i] = new ImageIcon(getURL(baseURL,
                                               prefix + (i+1)
                                               + ".gif"));
            }
            finishedLoading = true;
            timer.start(); //Start the animation.
            return imgs;
        }
        ...
    };
    worker.start();
    ...
}

To create an ImageIcon and load it with an image, you specify the image file's URL to the ImageIcon's constructor. The getURL method is implemented as follows:

protected URL getURL(URL codeBase, String filename) {
    URL url = null;

    try {
        url = new URL(codeBase, filename);
    } catch (java.net.MalformedURLException e) {
        System.out.println("Couldn't create image: "
                           + "badly specified URL");
        return null;
    }

    return url;
}

Providing an OBJECT/EMBED Tag for Java Plug-in

To run, an applet must be included in an HTML page. If your applet's users have Swing-enabled browsers, then you can include the applet in an HTML page with an <APPLET> tag. Here's the <APPLET> tag for the cartwheeling Duke applet:

<applet code="TumbleItem.class" 
        codebase="example-swing/"
        archive="tumble.jar"
        width="600" height="95">
    <param name="maxwidth" value="120">
    <param name="nimgs" value="17">
    <param name="offset" value="-57">
    <param name="img" value="images/tumble">

Your browser is completely ignoring the &lt;APPLET&gt; tag!

</applet>

To find out about the various <APPLET> tag parameters, refer to Test Driving an Applet and Using the APPLET Tag.

If your applet's users don't have a Swing-enabled browser, then they'll need to use Java Plug-in to run the applet. Java Plug-in requires that an applet be included in an HTML page with an <OBJECT> tag or <EMBED> tag. You can download a free tool that automatically generates the necessary tags from an <APPLET> tag. To download Java Plug-in and the HTML conversion tool, and for related documentation, go to the Java Plug-in home page .

Because Plug-in can take a while to download and load into the browser, it's considerate to give users advance warning that a page contains an applet. You might have noticed that the tutorial's applets don't run the same page as the text that describes the applet. Instead, we provide a screenshot of the applet running and a link that brings up a separate browser window in which to run the applet. This provides a better experience because they can choose whether or not to visit a page that contains an applet.

The JApplet API

The next table lists the interesting methods that JApplet adds to the applet API. They give you access to features provided by the root pane. Other methods you might use are defined by the Component and Applet classes. See Component Methods for a list of commonly used Component methods, and Taking Advantage of the Applet API for help in using Applet methods.

Method	Purpose
void setContentPane(Container) Container getContentPane()	Set or get the applet's content pane. The content pane contains the applet's visible GUI components and should be opaque.
JRootPane createRootPane() void setRootPane(JRootPane) JRootPane getRootPane()	Create, set, or get the applet's root pane. The root pane manages the interior of the applet including the content pane, the glass pane, and so on.
void setJMenuBar(JMenuBar) JMenuBar getJMenuBar()	Set or get the applet's menu bar to manage a set of menus for the frame.
void setGlassPane(Component) Component getGlassPane()	Set or get the applet's glass pane. You can use the glass pane to intercept mouse events.
void setLayeredPane(JLayeredPane) JLayeredPane getLayeredPane()	Set or get the applet's layered pane. You can use the frame's layered pane to put components on top of or behind other components.

Applet Examples

This table shows examples of Swing applets and where those examples are described.

Example	Where Described	Notes
TumbleItem	This page	An animation applet
HelloSwingApplet	Running Swing Applets	The simplest of all Swing applets -- it contains only a label.
AppletDemo	Running Swing Applets	The applet version of the button demo program. Can be run either as an application or as an applet.
IconDemoApplet	How to Use Icons	An applet for showing photos.
Several examples.	Using Layout Managers	You can run several applets from the page listed. Each applet demonstrates a different layout manager.
Several examples.	Some Simple Event-Handling Examples	You can run several applets from the page listed. Each applet shows how to handle different types of events.

Start of Tutorial > Start of Trail > Start of Lesson

Search Feedback Form

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