8.6 The JApplet Class

JApplet is a simple extension of java.applet.Applet to use when creating Swing programs designed to be used in a web browser (or appletviewer). As a direct subclass of Applet, JApplet is used in much the same way, with the init( ), start( ), and stop( ) methods still playing critical roles. The primary thing JApplet provides that Applet does not is the use of a JRootPane as its single display component. The properties and methods described below should look a lot like those described in the previous sections on JFrame and JWindow. Figure 8-11 shows a JApplet running in appletviewer.

Figure 8-11. A JApplet running in the SDK appletviewer

Here's the code for this simple applet:

// SimpleApplet.java // import javax.swing.*; import javax.swing.border.*; import java.awt.*; public class SimpleApplet extends JApplet {   public void init( ) {     JPanel p = new JPanel( );     p.setLayout(new GridLayout(2, 2, 2, 2));     p.add(new JLabel("Username"));     p.add(new JTextField( ));     p.add(new JLabel("Password"));     p.add(new JPasswordField( ));     Container content = getContentPane( );     content.setLayout(new GridBagLayout( )); // Used to center the panel     content.add(p);   } }

Using JApplet in browsers is a bit trickier. You should have a browser that supports at least the 1.2 release of the JRE. You typically end up using the Java Plug-in. The Plug-in allows you to specify which version of the JRE you want to use. The applet code itself doesn't change, but your HTML page is quite a bit different. For example, here's the simple HTML page with the <applet> tag to use with the appletviewer:

<HTML> <HEAD><TITLE>JApplet Demo Page</TITLE></HEAD> <BODY BGCOLOR="#FFFFFF"> <H1>JApplet Demo Page</H1> If you see the login applet in this window, your plug-in has been successfully installed and configured. <b>Congratulations!</b> <hr> <applet code=SimpleApplet width=300 height=200>   <param name="bogus" value="just testing"> </applet> <hr> </BODY> </HTML>

Pretty straightforward. Now here's the converted code that should replace the <applet> tag from the example above. We used the SDK's HtmlConverter application to produce this page that brings up the applet from Figure 8-11 in a browser with the Java Plug-in:

<!--"CONVERTED_APPLET"--> <!-- HTML CONVERTER --> <OBJECT      class     WIDTH = 300 HEIGHT = 200       codebase="http://java.sun.com/products/plugin/autodl/jinstall-1_3-win.cab#Version=1,3,0,0">     <PARAM NAME = CODE VALUE = SimpleApplet >     <PARAM NAME="type" VALUE="application/x-java-applet;version=1.3">     <PARAM NAME="scriptable" VALUE="false">     <PARAM NAME = "bogus" VALUE ="just testing">     <COMMENT>     <EMBED              type="application/x-java-applet;version=1.3"              CODE = SimpleApplet             WIDTH = 300             HEIGHT = 200              bogus = "just testing"          scriptable=false          pluginspage="http://java.sun.com/products/plugin/index.html#download">         <NOEMBED>                  </NOEMBED>     </EMBED>     </COMMENT> </OBJECT> <!--"END_CONVERTED_APPLET"-->

Not an obvious conversion, but fortunately, you can always use the converter tool to help you out. (You may want to run the converter from the 1.3 release of the SDK. This will allow you to support "1.3 and higher" if you want maximum compatibility for old versions of the Plug-in.) If you get deep into producing Swing applets, you should check out the full details on the Java Plug-in at http://java.sun.com/products/plugin/index.html.

One happy note to end this discussion: more and more browsers are supporting the Java Plug-in with a "use this plug in as the default for applets" type of option. With this in place, you don't need the converted HTML at all. The regular <applet> tags run just swell.

8.6.1 Hiding the Warning Message

Older versions of the popular browsers do not allow applets to access the system event queue. As a result, a warning message is printed to the Java console, indicating that the applet attempted to access the system event queue and failed. If you find this warning sufficiently annoying, Swing provides a workaround that allows you to suppress it. (You don't have to worry about this if you use the Java Plug-in; see the previous section for more details.) Just implement a constructor for your applet with the following code:

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

In AWT, applets rarely (if ever) had constructors. With Swing, a constructor (which must have no arguments) is a good place to set client properties like this one.

8.6.2 Threading Issues

Since JApplets are typically used within an existing Java virtual machine (from the web browser), you need to be careful about Swing threading issues. A good rule of thumb is that any adding or manipulation of components should be done in the init( ) method. If you choose to interact with Swing components in the start( ) method, you should be sure to execute the code in the event dispatch thread using the SwingUtilities.invokeLater( ) or SwingUtilities.invokeAndWait( ) methods.

// SimpleApplet2.java // import javax.swing.*; import java.awt.*; public class SimpleApplet2 extends JApplet {   public SimpleApplet2( ) {     // Suppress warning message on older versions if needed:     //   getRootPane( ).putClientProperty("defeatSystemEventQueueCheck",      //   Boolean.TRUE);   }   public void start( ) {     SwingUtilities.invokeLater(new Runnable( ) {       public void run( ) { // Run in the event thread.         JPanel p = new JPanel( );         p.setLayout(new GridLayout(2, 2, 2, 2));         p.add(new JLabel("Username"));         p.add(new JTextField( ));         p.add(new JLabel("Password"));         p.add(new JPasswordField( ));         Container content = getContentPane( );         content.setLayout(new GridBagLayout( )); // Used to center the panel         content.add(p);         validate( );       }     });   } }

Of course, in this example, we could just move this code to init( ) and safely do away with invokeLater( ). But if you start working with things like dynamic tables or trees in your applet, this approach is ideal. For more information on threading issues in Swing, see Chapter 1 for an introduction and Chapter 28 for more details.

8.6.3 Properties

JApplet defines the properties and default values shown in Table 8-10. The contentPane , glassPane, layeredPane, and JMenuBar properties are really properties of JRootPane (described earlier in the chapter). Direct access is provided to them for convenience.

Table 8-10. JApplet properties
Property	Data type	get	is	set	Default value
`accessibleContext`^o	`AccessibleContext`	·			`JApplet.AccessibleJApplet( )`
`contentPane`^o	`Container`	·		·	From `rootPane`
`glassPane`^o	`Component`	·		·	From `rootPane`
`layeredPane`^o	`JLayeredPane`	·		·	From `rootPane`
`layout`^o	`LayoutManager`	·		·	`BorderLayout( )`
`JMenuBar`^o	`JMenuBar`	·		·	From `rootPane`
`rootPane`^{o, *}	`JRootPane`	·		·	`JRootPane( )`
`rootPaneCheckingEnabled`^p	`boolean`		·	·	`true`
^ooverridden, ^pprotected *The `setRootPane()` method is protected. See also the `java.applet.Applet` class.

The layout property is listed here because JApplet overrides setLayout( ) to throw an Error if an attempt is made to change the layout manager, rather than set the layout manager of the applet's content pane.

The rootPane property is set when the applet is created. It cannot be changed via public methods.

8.6.4 Constructor

public JApplet( ): Create a new applet and ensure that the timerQueue is running. This is how browsers (and appletviewer) create new applets. If you supply a constructor with an applet, perhaps to disable event queue checking, remember that browsers expect an applet constructor to have no arguments. The constructor sets the applet's foreground color to black and its background color to white.

8.6.5 User Interface Method

public void update(Graphics g): Override Container.update( ) to do nothing but call paint( ). This is consistent with the implementation of update( ) provided by JComponent (and the implementation used by JFrame).