Simple Applet Display Methods, Requesting Repainting, Using the Status Window & The HTML APPLET Tag - Java Tutorials

Simple Applet Display Methods

As we’ve mentioned, applets are displayed in a window and they use the AWT to perform input and output. Although we will examine the methods, procedures, and techniques necessary to fully handle the AWT windowed environment in subsequent chapters, a few are described here, because we will use them to write sample applets.

As we described in Chapter 12, to output a string to an applet, use drawString( ), which is a member of the Graphics class. Typically, it is called from within either update( ) or paint( ). It has the following general form:

      void drawString(String message, int x, int y)

Here, message is the string to be output beginning at x,y. In a Java window, the upper-left corner is location 0,0. The drawString( ) method will not recognize newline characters. If you want to start a line of text on another line, you must do so manually, specifying the precise X,Y location where you want the line to begin. (As you will see in later chapters, there are techniques that make this process easy.)

To set the background color of an applet’s window, use setBackground( ). To set the foreground color (the color in which text is shown, for example), use setForeground( ). These methods are defined by Component, and they have the following general forms:

      void setBackground(Color newColor)

      void setForeground(Color newColor)

Here, newColor specifies the new color. The class Color defines the constants shown here that can be used to specify colors:

      Color.black 

      Color.magenta

      Color.blue 

      Color.orange

      Color.cyan 

      Color.pink

      Color.darkGray 

      Color.red

      Color.gray 

      Color.white

      Color.green 

      Color.yellow

      Color.lightGray

For example, this sets the background color to green and the text color to red:

  setBackground(Color.green);

  setForeground(Color.red);

A good place to set the foreground and background colors is in the init( ) method. Of course, you can change these colors as often as necessary during the execution of your applet. The default foreground color is black. The default background color is light gray.

You can obtain the current settings for the background and foreground colors by calling getBackground( ) and getForeground( ), respectively. They are also defined by Component and are shown here:

      Color getBackground( )

      Color getForeground( )

Here is a very simple applet that sets the background color to cyan, the foreground color to red, and displays a message that illustrates the order in which the init( ), start( ), and paint( ) methods are called when an applet starts up:

  /* A simple applet that sets the foreground and

     background colors and outputs a string. */

  import java.awt.*;

  import java.applet.*;

  /*

  <applet code="Sample" width=300 height=50>

  </applet>

  */

  public class Sample extends Applet{

    String msg;

    // set the foreground and background colors.

    public void init() {

      setBackground(Color.cyan);

      setForeground(Color.red);

      msg = "Inside init( ) --";

    }

    // Initialize the string to be displayed.

    public void start() {

      msg += " Inside start( ) --";

    }

    // Display msg in applet window.

    public void paint(Graphics g) {

      msg += " Inside paint( ).";

      g.drawString(msg, 10, 30);

    }

  }

The methods stop( ) and destroy( ) are not overridden, because they are not needed by this simple applet.

Requesting Repainting

As a general rule, an applet writes to its window only when its update( ) or paint( ) method is called by the AWT. This raises an interesting question: How can the applet itself cause its window to be updated when its information changes? For example, if an applet is displaying a moving banner, what mechanism does the applet use to update the window each time this banner scrolls? Remember, one of the fundamental architectural constraints imposed on an applet is that it must quickly return control to the AWT run-time system. It cannot create a loop inside paint( ) that repeatedly scrolls the banner, for example. This would prevent control from passing back to the AWT. Given this constraint, it may seem that output to your applet’s window will be difficult at best. Fortunately, this is not the case. Whenever your applet needs to update the information displayed in its window, it simply calls repaint( ).

The repaint( ) method is defined by the AWT. It causes the AWT run-time system to execute a call to your applet’s update( ) method, which, in its default implementation, calls paint( ). Thus, for another part of your applet to output to its window, simply store the output and then call repaint( ). The AWT will then execute a call to paint( ), which can display the stored information. For example, if part of your applet needs to output a string, it can store this string in a String variable and then call repaint( ). Inside paint( ), you will output the string using drawString( ).

The repaint( ) method has four forms. Let’s look at each one, in turn. The simplest version of repaint( ) is shown here:

      void repaint( )

This version causes the entire window to be repainted. The following version specifies a region that will be repainted:

      void repaint(int left, int top, int width, int height)

Here, the coordinates of the upper-left corner of the region are specified by left and top, and the width and height of the region are passed in width and height. These dimensions are specified in pixels. You save time by specifying a region to repaint. Window updates are costly in terms of time. If you need to update only a small portion of the window, it is more efficient to repaint only that region.

Calling repaint( ) is essentially a request that your applet be repainted sometime soon. However, if your system is slow or busy, update( ) might not be called immediately. Multiple requests for repainting that occur within a short time can be collapsed by the AWT in a manner such that update( ) is only called sporadically. This can be a problem in many situations, including animation, in which a consistent update time is necessary. One solution to this problem is to use the following forms of repaint( ):

      void repaint(long maxDelay)

      void repaint(long maxDelay, int x, int y, int width, int height)

Here, maxDelay specifies the maximum number of milliseconds that can elapse before update( ) is called. Beware, though. If the time elapses before update( ) can be called, it isn’t called. There’s no return value or exception thrown, so you must be careful.

It is possible for a method other than paint( ) or update( ) to output to an applet’s window. To do so, it must obtain a graphics context by calling getGraphics( ) (defined by Component) and then use this context to output to the window. However, for most applications, it is better and easier to route window output through paint( ) and to call repaint( ) when the contents of the window change.

A Simple Banner Applet

To demonstrate repaint( ), a simple banner applet is developed. This applet scrolls a message, from right to left, across the applet’s window. Since the scrolling of the message is a repetitive task, it is performed by a separate thread, created by the applet when it is initialized. The banner applet is shown here:

  /* A simple banner applet.

     This applet creates a thread that scrolls

     the message contained in msg right to left

     across the applet's window.

  */

  import java.awt.*;

  import java.applet.*;

  /*

  <applet code="SimpleBanner" width=300 height=50>

  </applet>

  */

  public class SimpleBanner extends Applet implements Runnable {

    String msg = " A Simple Moving Banner.";

    Thread t = null;

    int state;

    boolean stopFlag;

    // Set colors and initialize thread.

    public void init() {

      setBackground(Color.cyan);

      setForeground(Color.red);

    }

    // Start thread

    public void start() {

      t = new Thread(this);

      stopFlag = false;

      t.start();

    }

    // Entry point for the thread that runs the banner.

    public void run() {

      char ch;

      // Display banner

      for( ; ; ) {

        try {

          repaint();

          Thread.sleep(250);

          ch = msg.charAt(0);

          msg = msg.substring(1, msg.length());

          msg += ch;

          if(stopFlag)

            break;

        } catch(InterruptedException e) {}

      }

    }

    // Pause the banner.

    public void stop() {

      stopFlag = true;

      t = null;

    }

    // Display the banner.

    public void paint(Graphics g) {

      g.drawString(msg, 50, 30);

    }

  }

Let’s take a close look at how this applet operates. First, notice that SimpleBanner extends Applet, as expected, but it also implements Runnable. This is necessary, since the applet will be creating a second thread of execution that will be used to scroll the banner. Inside init( ), the foreground and background colors of the applet are set.

After initialization, the AWT run-time system calls start( ) to start the applet running. Inside start( ), a new thread of execution is created and assigned to the Thread variable t. Then, the boolean variable stopFlag, which controls the execution of the applet, is set to false. Next, the thread is started by a call to t.start( ). Remember that t.start( ) calls a method defined by Thread, which causes run( ) to begin executing. It does not cause a call to the version of start( ) defined by Applet. These are two separate methods.

Inside run( ), the characters in the string contained in msg are repeatedly rotated left. Between each rotation, a call to repaint( ) is made. This eventually causes the paint( ) method to be called and the current contents of msg is displayed. Between each iteration, run( ) sleeps for a quarter of a second. The net effect of run( ) is that the contents of msg is scrolled right to left in a constantly moving display. The stopFlag variable is checked on each iteration. When it is true, the run( ) method terminates.

If a browser is displaying the applet when a new page is viewed, the stop( ) method is called, which sets stopFlag to true, causing run( ) to terminate. This is the mechanism used to stop the thread when its page is no longer in view. When the applet is brought back into view, start( ) is once again called, which starts a new thread to execute the banner.

Using the Status Window

In addition to displaying information in its window, an applet can also output a message to the status window of the browser or applet viewer on which it is running. To do so, call showStatus( ) with the string that you want displayed. The status window is a good place to give the user feedback about what is occurring in the applet, suggest options, or possibly report some types of errors. The status window also makes an excellent debugging aid, because it gives you an easy way to output information about your applet.

The following applet demonstrates showStatus( ):

  // Using the Status Window.

  import java.awt.*;

  import java.applet.*;

  /*

  <applet code="StatusWindow" width=300 height=50>

  </applet>

  */

  public class StatusWindow extends Applet{

    public void init() {

      setBackground(Color.cyan);

    }

    // Display msg in applet window.

    public void paint(Graphics g) {

      g.drawString("This is in the applet window.", 10, 20);

      showStatus("This is shown in the status window.");

    }

  }




The HTML APPLET Tag

The APPLET tag is used to start an applet from both an HTML document and from an applet viewer. (The newer OBJECT tag also works, but this book will use APPLET.) An applet viewer will execute each APPLET tag that it finds in a separate window, while web browsers like Netscape Navigator, Internet Explorer, and HotJava will allow many applets on a single page. So far, we have been using only a simplified form of the APPLET tag. Now it is time to take a closer look at it.

The syntax for the standard APPLET tag is shown here. Bracketed items are optional.

      < APPLET
        [CODEBASE = codebaseURL]
        CODE = appletFile
        [ALT = alternateText]
        [NAME = appletInstanceName]
        WIDTH = pixels HEIGHT = pixels
        [ALIGN = alignment]
        [VSPACE = pixels] [HSPACE = pixels]
      >
      [< PARAM NAME = AttributeName VALUE = AttributeValue>]
      [< PARAM NAME = AttributeName2 VALUE = AttributeValue>]
      . . .
      [HTML Displayed in the absence of Java]
      </APPLET>

Let’s take a look at each part now.

CODEBASE CODEBASE     is an optional attribute that specifies the base URL of the applet code, which is the directory that will be searched for the applet’s executable class file (specified by the CODE tag). The HTML document’s URL directory is used as the CODEBASE if this attribute is not specified. The CODEBASE does not have to be on the host from which the HTML document was read.

CODE     CODE is a required attribute that gives the name of the file containing your applet’s compiled .class file. This file is relative to the code base URL of the applet, which is the directory that the HTML file was in or the directory indicated by CODEBASE if set.

ALT     The ALT tag is an optional attribute used to specify a short text message that should be displayed if the browser understands the APPLET tag but can’t currently run Java applets. This is distinct from the alternate HTML you provide for browsers that don’t support applets.

NAME     NAME is an optional attribute used to specify a name for the applet instance. Applets must be named in order for other applets on the same page to find them by name and communicate with them. To obtain an applet by name, use getApplet( ), which is defined by the AppletContext interface.

WIDTH AND HEIGHT     WIDTH and HEIGHT are required attributes that give the size (in pixels) of the applet display area.

ALIGN     ALIGN is an optional attribute that specifies the alignment of the applet. This attribute is treated the same as the HTML IMG tag with these possible values: LEFT, RIGHT, TOP, BOTTOM, MIDDLE, BASELINE, TEXTTOP, ABSMIDDLE, and ABSBOTTOM.

VSPACE AND HSPACE     These attributes are optional. VSPACE specifies the space, in pixels, above and below the applet. HSPACE specifies the space, in pixels, on each side of the applet. They’re treated the same as the IMG tag’s VSPACE and HSPACE attributes.

PARAM NAME AND VALUE     The PARAM tag allows you to specify appletspecific arguments in an HTML page. Applets access their attributes with the getParameter( ) method.

HANDLING OLDER BROWSERS     Some very old web browsers can’t execute applets and don’t recognize the APPLET tag. Although these browsers are now nearly extinct (having been replaced by Java-compatible ones), you may need to deal with them occasionally. The best way to design your HTML page to deal with such browsers is to include HTML text and markup within your <applet></applet> tags. If the applet tags are not recognized by your browser, you will see the alternate markup. If Java is available, it will consume all of the markup between the <applet></applet> tags and disregard the alternate markup.

Here’s the HTML to start an applet called SampleApplet in Java and to display a message in older browsers:

  <applet code="SampleApplet" width=200 height=40>
   If you were driving a Java powered browser,
   you'd see &quote;A Sample Applet&quote; here.<p>

  </applet>